get-shit-pretty 0.6.2 → 0.6.3

package/README.md

@@ -258,7 +258,7 @@ GSP works across all major AI coding tools. The installer converts Claude Code's
 | Gemini CLI | `~/.gemini/` | `~/.gemini/skills/` | `~/.gemini/agents/` |
 | Codex CLI | `~/.codex/` | `~/.agents/skills/` | — |
 
-> **Codex note:** Skills are discovered at `~/.agents/skills/`, not `~/.codex/skills/`. Config and bundle files (prompts, templates, references) stay at `~/.codex/get-shit-pretty/`. Codex does not support agent `.md` files.
+> **Codex note:** Skills are discovered at `~/.agents/skills/`, not `~/.codex/skills/`. Config and bundle files (templates, references) stay at `~/.codex/get-shit-pretty/`. Codex does not support agent `.md` files.
 
 ---
 
@@ -308,14 +308,14 @@ npx get-shit-pretty --codex --global --uninstall
 </details>
 
 <details>
-<summary><strong>Use as Claude Code plugin</strong></summary>
+<summary><strong>Local development</strong></summary>
 
 ```bash
-# From a project directory:
-claude --plugin-dir /path/to/get-shit-pretty
+# From the repo root:
+node bin/install.js --claude --local
 ```
 
-Uses the `.claude-plugin/plugin.json` manifest. Skills, agents, and hooks load directly from source — no install step needed.
+Symlinks skills and agents to `.claude/` — edits to `gsp/` are reflected immediately.
 
 </details>
 
@@ -325,15 +325,13 @@ Uses the `.claude-plugin/plugin.json` manifest. Skills, agents, and hooks load d
 
 ```
 get-shit-pretty/
-├── .claude-plugin/        Plugin manifest (plugin.json)
 ├── bin/
 │   └── install.js         Multi-runtime installer
 ├── scripts/               Hook scripts and utilities
 ├── gsp/                   Source of truth for all content
 │   ├── agents/            15 subagents (gsp-*.md)
-│   ├── skills/            30 skills (*/SKILL.md)
-│   ├── hooks/             Plugin-level hooks (hooks.json)
-│   ├── prompts/           12 agent system prompts
+│   ├── skills/            38 skills (*/SKILL.md)
+│   ├── hooks/             Hooks (hooks.json)
 │   ├── templates/         Config, state, brief, roadmap templates
 │   └── references/        Shared reference material
 ├── dev/                   Internal dev tools (not installed)
@@ -356,9 +354,6 @@ Edit source under `gsp/` — never edit inside `.claude/` or other runtime dirs
 # Install locally with symlinks
 node bin/install.js --claude --local
 
-# Test as a plugin
-claude --plugin-dir .
-
 # Run the integrity test suite
 bash dev/scripts/audit-tests.sh
 ```

package/bin/install.js

@@ -167,7 +167,7 @@ function center(text, width) {
 }
 
 const columns = process.stdout.columns || 80;
-const rampText = `${c.accent}░▒▓█${c.reset} ${c.bold} GET SHIT PRETTY ${c.reset} ${c.accent}█▓▒░${c.reset}`;
+const rampText = `${c.accent}░▒▓█${c.reset} ${c.bold} GET SHIT PRETTY ${c.reset} ${c.dim}v${pkg.version}${c.reset} ${c.accent}█▓▒░${c.reset}`;
 const boxWidth = 48;
 const innerWidth = boxWidth - 2; // inside the border chars
 const showSparkles = columns >= 44;
@@ -197,7 +197,7 @@ const banner = '\n' +
   (showSparkles ? sparkle('dense') + '\n' : '') +
   bottomBorder + '\n' +
   '\n' +
-  `  ${c.bold}${c.accent}/gsp:${c.reset} ${c.tertiary}◇◇${c.reset}  ${c.dim}v${pkg.version}${c.reset}\n` +
+  `  ${c.bold}${c.accent}/gsp${c.reset} ${c.tertiary}◇◇${c.reset}\n` +
   `  ${c.dim}${tagline}${c.reset}\n`;
 
 console.log(banner);
@@ -395,7 +395,7 @@ function applyOpencodeBodyReplacements(content) {
   converted = converted.replace(/\bSlashCommand\b/g, 'skill');
   converted = converted.replace(/\bSkill\b(?=\s+tool\b)/g, 'skill');
   converted = converted.replace(/\bTodoWrite\b/g, 'todowrite');
-  converted = converted.replace(/\/gsp:/g, '/gsp-');
+  converted = converted.replace(/\/gsp:/g, '/gsp-');  // legacy: source may still have /gsp: in older versions
   converted = converted.replace(/~\/\.claude\b/g, '~/.config/opencode');
   converted = converted.replace(/subagent_type="general-purpose"/g, 'subagent_type="general"');
   // Convert Claude agent spawning to OpenCode subagent delegation
@@ -806,7 +806,8 @@ function convertClaudeSkillToGemini(content, skillName) {
  */
 function applyCodexBodyReplacements(content) {
   let converted = content;
-  converted = converted.replace(/\/gsp:/g, '$gsp-');
+  converted = converted.replace(/\/gsp:/g, '$gsp-');  // legacy: source may still have /gsp: in older versions
+  converted = converted.replace(/\/gsp-/g, '$gsp-');
   converted = converted.replace(/~\/\.claude\b/g, '~/.codex');
   converted = converted.replace(/\bAskUserQuestion\b/g, 'ask the user');
   converted = converted.replace(/\bSlashCommand\b/g, 'skill');
@@ -892,15 +893,7 @@ function convertClaudeSkillToCodex(content, skillName) {
 function copyOpencodeSkills(srcDir, destDir, pathPrefix) {
   if (!fs.existsSync(srcDir)) return 0;
   fs.mkdirSync(destDir, { recursive: true });
-
-  // Clean old gsp- skill dirs
-  if (fs.existsSync(destDir)) {
-    for (const entry of fs.readdirSync(destDir, { withFileTypes: true })) {
-      if (entry.isDirectory() && entry.name.startsWith('gsp-')) {
-        fs.rmSync(path.join(destDir, entry.name), { recursive: true });
-      }
-    }
-  }
+  cleanStaleGspDirs(destDir);
 
   let count = 0;
   const skillDirs = fs.readdirSync(srcDir, { withFileTypes: true });
@@ -910,18 +903,15 @@ function copyOpencodeSkills(srcDir, destDir, pathPrefix) {
     const skillMd = path.join(srcDir, dir.name, 'SKILL.md');
     if (!fs.existsSync(skillMd)) continue;
 
-    // OpenCode skill names: lowercase, hyphens, no consecutive hyphens, 1-64 chars
-    // Prefix with gsp- so they don't collide, unless already prefixed
-    const skillName = dir.name.startsWith('gsp-') ? dir.name : `gsp-${dir.name}`;
-    const skillDest = path.join(destDir, skillName);
+    const skillDest = path.join(destDir, dir.name);
     fs.mkdirSync(skillDest, { recursive: true });
 
     let content = fs.readFileSync(skillMd, 'utf8');
     content = content.replace(/~\/\.claude\//g, pathPrefix);
     content = content.replace(/\.\/\.claude\//g, './.opencode/');
-    content = convertClaudeSkillToOpencode(content, skillName);
+    content = convertClaudeSkillToOpencode(content, dir.name);
     fs.writeFileSync(path.join(skillDest, 'SKILL.md'), content);
-    copySiblingFiles(path.join(srcDir, dir.name), skillDest, pathPrefix);
+    copySiblingFiles(path.join(srcDir, dir.name), skillDest);
     count++;
   }
 
@@ -930,13 +920,14 @@ function copyOpencodeSkills(srcDir, destDir, pathPrefix) {
 
 /**
  * Copy skills/ source to Codex skill structure.
- * skills/<name>/SKILL.md → .agents/skills/gsp-<name>/SKILL.md
+ * skills/gsp-<name>/SKILL.md → .agents/skills/gsp-<name>/SKILL.md
  *
  * Codex expects: .agents/skills/<name>/SKILL.md with YAML frontmatter (name + description).
  */
 function copyCodexSkillsFromSource(srcDir, destDir, pathPrefix) {
   if (!fs.existsSync(srcDir)) return 0;
   fs.mkdirSync(destDir, { recursive: true });
+  cleanStaleGspDirs(destDir);
 
   let count = 0;
   const skillDirs = fs.readdirSync(srcDir, { withFileTypes: true });
@@ -945,15 +936,14 @@ function copyCodexSkillsFromSource(srcDir, destDir, pathPrefix) {
     const skillMd = path.join(srcDir, dir.name, 'SKILL.md');
     if (!fs.existsSync(skillMd)) continue;
 
-    const skillName = dir.name.startsWith('gsp-') ? dir.name : `gsp-${dir.name}`;
-    const skillDest = path.join(destDir, skillName);
+    const skillDest = path.join(destDir, dir.name);
     fs.mkdirSync(skillDest, { recursive: true });
 
     let content = fs.readFileSync(skillMd, 'utf8');
     content = content.replace(/~\/\.claude\//g, pathPrefix);
-    content = convertClaudeSkillToCodex(content, skillName);
+    content = convertClaudeSkillToCodex(content, dir.name);
     fs.writeFileSync(path.join(skillDest, 'SKILL.md'), content);
-    copySiblingFiles(path.join(srcDir, dir.name), skillDest, pathPrefix);
+    copySiblingFiles(path.join(srcDir, dir.name), skillDest);
     count++;
   }
   return count;
@@ -961,22 +951,14 @@ function copyCodexSkillsFromSource(srcDir, destDir, pathPrefix) {
 
 /**
  * Copy skills/ source to Gemini skill structure.
- * skills/<name>/SKILL.md → .gemini/skills/gsp-<name>/SKILL.md
+ * skills/gsp-<name>/SKILL.md → .gemini/skills/gsp-<name>/SKILL.md
  *
  * Gemini expects: .gemini/skills/<name>/SKILL.md with YAML frontmatter (name + description).
  */
 function copyGeminiSkills(srcDir, destDir, pathPrefix) {
   if (!fs.existsSync(srcDir)) return 0;
   fs.mkdirSync(destDir, { recursive: true });
-
-  // Clean old gsp- skill dirs
-  if (fs.existsSync(destDir)) {
-    for (const entry of fs.readdirSync(destDir, { withFileTypes: true })) {
-      if (entry.isDirectory() && entry.name.startsWith('gsp-')) {
-        fs.rmSync(path.join(destDir, entry.name), { recursive: true });
-      }
-    }
-  }
+  cleanStaleGspDirs(destDir);
 
   let count = 0;
   const skillDirs = fs.readdirSync(srcDir, { withFileTypes: true });
@@ -985,16 +967,15 @@ function copyGeminiSkills(srcDir, destDir, pathPrefix) {
     const skillMd = path.join(srcDir, dir.name, 'SKILL.md');
     if (!fs.existsSync(skillMd)) continue;
 
-    const skillName = dir.name.startsWith('gsp-') ? dir.name : `gsp-${dir.name}`;
-    const skillDest = path.join(destDir, skillName);
+    const skillDest = path.join(destDir, dir.name);
     fs.mkdirSync(skillDest, { recursive: true });
 
     let content = fs.readFileSync(skillMd, 'utf8');
     content = content.replace(/~\/\.claude\//g, pathPrefix);
     content = content.replace(/\.\/\.claude\//g, './.gemini/');
-    content = convertClaudeSkillToGemini(content, skillName);
+    content = convertClaudeSkillToGemini(content, dir.name);
     fs.writeFileSync(path.join(skillDest, 'SKILL.md'), content);
-    copySiblingFiles(path.join(srcDir, dir.name), skillDest, pathPrefix);
+    copySiblingFiles(path.join(srcDir, dir.name), skillDest);
     count++;
   }
   return count;
@@ -1036,49 +1017,64 @@ function copyAgents(srcDir, destDir, pathPrefix, runtime, { clean = false } = {}
 }
 
 /**
- * Copy Claude Code skills (global install path — no body conversion, only path replacement).
- * Returns skill count.
+ * Remove stale GSP skill dirs/symlinks (gsp-* and get-shit-pretty) from a target directory.
+ * Handles broken symlinks via lstat fallback.
  */
+function cleanStaleGspDirs(dir) {
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const name = entry.name;
+    if (!name.startsWith('gsp-') && name !== 'get-shit-pretty') continue;
+    const entryPath = path.join(dir, name);
+    try {
+      // withFileTypes doesn't resolve broken symlinks — use lstat for those
+      if (entry.isSymbolicLink()) { fs.unlinkSync(entryPath); count++; }
+      else if (entry.isDirectory()) { fs.rmSync(entryPath, { recursive: true }); count++; }
+      else {
+        // broken symlink: withFileTypes returns isFile=false, isDir=false, isSymlink=false
+        const s = fs.lstatSync(entryPath);
+        if (s.isSymbolicLink()) { fs.unlinkSync(entryPath); count++; }
+      }
+    } catch {}
+  }
+  return count;
+}
+
 /**
  * Recursively copy sibling files in a skill directory (everything except SKILL.md).
- * All sibling files are copied verbatim — no path replacement applied.
  */
-function copySiblingFiles(srcDir, destDir, pathPrefix) {
+function copySiblingFiles(srcDir, destDir) {
   for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-    if (entry.name === 'SKILL.md') continue; // already handled by caller
+    if (entry.name === 'SKILL.md') continue;
     const srcPath = path.join(srcDir, entry.name);
     const destPath = path.join(destDir, entry.name);
     if (entry.isDirectory()) {
       fs.mkdirSync(destPath, { recursive: true });
-      copySiblingFiles(srcPath, destPath, pathPrefix);
+      copySiblingFiles(srcPath, destPath);
     } else {
       fs.copyFileSync(srcPath, destPath);
     }
   }
 }
 
+/**
+ * Copy Claude Code skills (global install — no body conversion, only path replacement).
+ */
 function copyClaudeSkills(srcDir, destDir, pathPrefix) {
   fs.mkdirSync(destDir, { recursive: true });
-
-  // Clean old gsp- skill dirs
-  for (const entry of fs.readdirSync(destDir, { withFileTypes: true })) {
-    if (entry.isDirectory() && (entry.name.startsWith('gsp-') || entry.name === 'get-shit-pretty')) {
-      fs.rmSync(path.join(destDir, entry.name), { recursive: true });
-    }
-  }
+  cleanStaleGspDirs(destDir);
 
   let skillCount = 0;
   for (const dir of fs.readdirSync(srcDir, { withFileTypes: true })) {
     if (!dir.isDirectory()) continue;
     const skillMd = path.join(srcDir, dir.name, 'SKILL.md');
     if (!fs.existsSync(skillMd)) continue;
-    const skillName = dir.name.startsWith('gsp-') ? dir.name : `gsp-${dir.name}`;
-    const destSkillDir = path.join(destDir, skillName);
+    const destSkillDir = path.join(destDir, dir.name);
     fs.mkdirSync(destSkillDir, { recursive: true });
     let content = fs.readFileSync(skillMd, 'utf8');
     content = content.replace(/~\/\.claude\//g, pathPrefix);
     fs.writeFileSync(path.join(destSkillDir, 'SKILL.md'), content);
-    copySiblingFiles(path.join(srcDir, dir.name), destSkillDir, pathPrefix);
+    copySiblingFiles(path.join(srcDir, dir.name), destSkillDir);
     skillCount++;
   }
   return skillCount;
@@ -1201,14 +1197,8 @@ function installLocalSymlinks(targetDir, src) {
   const skillsDest = path.join(targetDir, 'skills');
   fs.mkdirSync(skillsDest, { recursive: true });
 
-  // Clean old GSP skill dirs
-  for (const entry of fs.readdirSync(skillsDest, { withFileTypes: true })) {
-    if (entry.isDirectory() && (entry.name.startsWith('gsp-') || entry.name === 'get-shit-pretty')) {
-      fs.rmSync(path.join(skillsDest, entry.name), { recursive: true });
-    }
-  }
-
   const skillsSrc = path.join(gspRoot, 'skills');
+  cleanStaleGspDirs(skillsDest);
   let skillCount = 0;
   for (const dir of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
     if (!dir.isDirectory()) continue;
@@ -1227,15 +1217,20 @@ function installLocalSymlinks(targetDir, src) {
     console.log(`  ${c.success}✓${c.reset} Removed legacy commands/gsp`);
   } catch {}
 
-  // ── Bundle symlinks (prompts, templates, references → runtime root) ──
-  // Clean up legacy get-shit-pretty/ bundle dir
+  // ── Bundle symlinks (templates, references → 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 dir of ['prompts', 'templates', 'references']) {
+  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}/`);
@@ -1267,6 +1262,16 @@ function installLocalSymlinks(targetDir, src) {
     process.exit(1);
   }
 
+  // Warn if GSP skills also exist globally (may cause duplicates)
+  const globalSkillsDir = path.join(getGlobalDir('claude', null), 'skills');
+  if (fs.existsSync(globalSkillsDir)) {
+    const dupes = fs.readdirSync(globalSkillsDir).filter(e => e.startsWith('gsp-'));
+    if (dupes.length > 0) {
+      console.log(`  ${yellow}!${reset} Found ${dupes.length} GSP skills in ${globalSkillsDir.replace(os.homedir(), '~')} — may cause duplicates`);
+      console.log(`    ${c.dim}To remove: node bin/install.js --claude --global --uninstall${c.reset}`);
+    }
+  }
+
   return true;
 }
 
@@ -1417,15 +1422,20 @@ function install(isGlobal, runtime = 'claude') {
     }
   }
 
-  // ── Bundle: prompts, templates, references → runtime root ──
-  // Clean up legacy get-shit-pretty/ bundle dir from previous installs
+  // ── Bundle: templates, references → runtime root ──
+  // Clean up legacy dirs from previous installs
   const legacyBundle = path.join(targetDir, 'get-shit-pretty');
   if (fs.existsSync(legacyBundle)) {
     fs.rmSync(legacyBundle, { recursive: true });
     console.log(`  ${c.success}✓${c.reset} Removed legacy get-shit-pretty/ bundle`);
   }
+  const legacyPromptsDir = path.join(targetDir, 'prompts');
+  if (fs.existsSync(legacyPromptsDir)) {
+    fs.rmSync(legacyPromptsDir, { recursive: true });
+    console.log(`  ${c.success}✓${c.reset} Removed legacy prompts/`);
+  }
 
-  const bundleDirs = ['prompts', 'templates', 'references'];
+  const bundleDirs = ['templates', 'references'];
   for (const dir of bundleDirs) {
     const dirSrc = path.join(gspRoot, dir);
     if (fs.existsSync(dirSrc)) {
@@ -1467,6 +1477,21 @@ function install(isGlobal, runtime = 'claude') {
     process.exit(1);
   }
 
+  // Warn if GSP skills exist in the other location (may cause duplicates)
+  if (runtime === 'claude') {
+    const otherDir = isGlobal
+      ? path.join(process.cwd(), '.claude', 'skills')
+      : path.join(getGlobalDir('claude', null), 'skills');
+    if (fs.existsSync(otherDir)) {
+      const dupes = fs.readdirSync(otherDir).filter(e => e.startsWith('gsp-'));
+      if (dupes.length > 0) {
+        const label = otherDir.replace(os.homedir(), '~');
+        console.log(`  ${yellow}!${reset} Found ${dupes.length} GSP skills in ${label} — may cause duplicates`);
+        console.log(`    ${c.dim}To remove: node bin/install.js --claude ${isGlobal ? '--local' : '--global'} --uninstall${c.reset}`);
+      }
+    }
+  }
+
   // ── Settings (Claude Code & Gemini only) ──
   const settingsPath = path.join(targetDir, 'settings.json');
   const settings = readSettings(settingsPath);
@@ -1545,7 +1570,7 @@ function uninstall(isGlobal, runtime = 'claude') {
       }
     }
   } else {
-    // All other runtimes: remove gsp- skill dirs
+    // All other runtimes (including Claude): remove gsp- skill dirs
     const skillsDir = path.join(targetDir, 'skills');
     if (fs.existsSync(skillsDir)) {
       let skillCount = 0;
@@ -1593,7 +1618,7 @@ function uninstall(isGlobal, runtime = 'claude') {
   }
 
   // Remove flattened bundle dirs
-  for (const dir of ['prompts', 'templates', 'references']) {
+  for (const dir of ['prompts', 'templates', 'references']) {  // prompts included for legacy cleanup
     const bundlePath = path.join(targetDir, dir);
     if (fs.existsSync(bundlePath)) {
       fs.rmSync(bundlePath, { recursive: true });
@@ -1726,8 +1751,8 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   }
 
   const runtimeLabel = getRuntimeLabel(runtime);
-  const helpCmd = isOpencode ? '/gsp-help' : isCodex ? '$gsp-help' : '/gsp:help';
-  const newCmd = isOpencode ? '/gsp-start' : isCodex ? '$gsp-start' : '/gsp:start';
+  const helpCmd = isCodex ? '$gsp-help' : '/gsp-help';
+  const newCmd = isCodex ? '$gsp-start' : '/gsp-start';
 
   // Show onboarding once (not per-runtime)
   if (!onboardingShown && !hasQuiet) {

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-accessibility-auditor
-description: Audits designs and code for WCAG 2.2 AA/AAA compliance. Spawned by /gsp:accessibility or /gsp:project-critique.
+description: Audits designs and code for WCAG 2.2 AA/AAA compliance. Spawned by /gsp-accessibility or /gsp-project-critique.
 tools: Read, Write, Grep, Glob
 disallowedTools: Edit, Bash
 maxTurns: 40
@@ -10,7 +10,7 @@ color: cyan
 ---
 
 <role>
-You are a GSP accessibility auditor spawned by `/gsp:accessibility` or `/gsp:project-critique`.
+You are a GSP accessibility auditor spawned by `/gsp-accessibility` or `/gsp-project-critique`.
 
 Act as Apple Accessibility Specialist. Your job is to audit designs or code against WCAG 2.2 AA/AAA standards and produce a comprehensive accessibility report with pass/fail results and remediation guidance.
 
@@ -39,7 +39,7 @@ Accessibility is a core quality requirement.
 
 ## Code Audit Mode
 
-When spawned by `/gsp:accessibility --code`, audit the actual codebase:
+When spawned by `/gsp-accessibility --code`, audit the actual codebase:
 
 1. **Grep for missing ARIA** — interactive elements without `role`, `aria-label`, `aria-labelledby`, `aria-describedby`
 2. **Alt text** — `<img>` tags without `alt`, icons without `aria-hidden` or labels

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-ascii-artist
-description: Easter egg agent that creates ASCII art for the terminal. Spawned by /gsp:art.
+description: Easter egg agent that creates ASCII art for the terminal. Spawned by /gsp-art.
 tools: Read, Bash
 disallowedTools: Edit, Write, Grep, Glob
 model: haiku

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-brand-auditor
-description: Audits existing brand identities for evolution. Spawned by /gsp:brand-audit.
+description: Audits existing brand identities for evolution. Spawned by /gsp-brand-audit.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
 disallowedTools: Edit
 maxTurns: 40
@@ -9,7 +9,7 @@ color: magenta
 ---
 
 <role>
-You are a GSP brand auditor spawned by `/gsp:brand-audit`.
+You are a GSP brand auditor spawned by `/gsp-brand-audit`.
 
 Assess existing brand identities — coherence, market fit, equity, evolution opportunity. Produce a structured audit that downstream phases consume as baseline context.
 </role>

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

@@ -0,0 +1,131 @@
+---
+name: gsp-brand-engineer
+description: Operationalizes brand identity for projects — assembles .yml, STYLE.md, token mapping, component specs, guidelines. Spawned by /gsp-brand-guidelines.
+tools: Read, Write, Edit, Bash, Grep, Glob
+maxTurns: 60
+permissionMode: acceptEdits
+color: magenta
+---
+
+<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/agents/gsp-brand-strategist.md

@@ -1,6 +1,6 @@
 ---
 name: gsp-brand-strategist
-description: Develops brand strategy, voice, and messaging. Spawned by /gsp:brand-strategy.
+description: Develops brand strategy, voice, and messaging. Spawned by /gsp-brand-strategy.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
 disallowedTools: Edit
 maxTurns: 40
@@ -9,7 +9,7 @@ color: magenta
 ---
 
 <role>
-You are a GSP brand strategist spawned by `/gsp:brand-strategy`.
+You are a GSP brand strategist spawned by `/gsp-brand-strategy`.
 
 Act as Head of Strategy at a top branding agency. Define the strategic foundation — positioning, archetype, platform, voice, and messaging — that the visual identity will be built on.