npx get-shit-pretty

Why GSP Exists

The gap between design and code is shrinking — but only from one direction.

Figma ships Code Connect, Dev Mode, MCP servers. Design tools are learning to speak code. That bridge is being built.

Coding tools aren't learning to speak design.

You can vibe-code an entire app in an afternoon. It works. It also looks like every other vibe-coded app — the same shadcn components, the same layouts, the same sea of sameness. No research, no brand thinking, no system, no critique. AI coding tools are powerful builders with zero design process.

AI didn't cause this. Skipping design thinking did.

GSP brings design fundamentals into the tools developers already use. Research. Brand. Design systems. UI patterns. Accessibility. Critique. The process that makes design consistent — running in your terminal.

For designers, it's the other direction. Code-first environments without giving up your process. Your design decisions become tokens, specs, and components — not a Figma file someone rebuilds from scratch.

Both disciplines. Same pipeline. Same environment. Design engineering — not designers learning to code or developers learning to design, but both working through the same system.

The missing half of the bridge.

How It Works

GSP follows a dual-diamond architecture — two complete design cycles that take you from nothing to shipped.

/gsp:start → picks up where you left off, routes you forward

         ◆ Diamond 1 — Branding                  ◆ Diamond 2 — Project
    ┌──────────────────────────┐           ┌──────────────────────────────┐
    │  brand-research          │           │  project-brief               │
    │    ↓                     │           │    ↓                         │
    │  brand-strategy          │           │  project-research            │
    │    (includes voice       │           │    ↓                         │
    │     and messaging)       │           │  project-design              │
    │    ↓                     │           │    ↓                         │
    │  brand-identity          │           │  project-critique ←──┐      │
    │    ↓                     │           │    ↓            loop │      │
    │  brand-patterns          │           │  project-build       │      │
    └──────────────────────────┘           │    ↓                 │      │
                                           │  project-review ─────┘      │
                                           └──────────────────────────────┘

All artifacts live in .design/ within your project directory.

◆ Diamond 1 — Branding

Build your brand from research to design system. Each phase feeds the next.

Already have a brand? Start with /gsp:brand-audit to assess what you have before evolving it.

1. /gsp:brand-research — Market landscape

Research your audience, competitors, and market position. Understand the terrain before making decisions.

Creates: .design/branding/{brand}/discover/

2. /gsp:brand-strategy — Who you are and how you sound

Define your archetype, positioning, and personality using the Kapferer Brand Identity Prism. Includes voice, tone spectrum, messaging framework, and naming conventions — verbal identity is part of strategy.

Creates: .design/branding/{brand}/strategy/

3. /gsp:brand-identity — How you look

Create your visual identity — logo directions, color palette, typography system, imagery style. Design decisions, not decoration.

Creates: .design/branding/{brand}/identity/

4. /gsp:brand-patterns — Your design system

Translate your brand into tokens, components, and a living design system. Everything codified and ready to build with.

Creates: .design/branding/{brand}/patterns/

◆ Diamond 2 — Project

Design and build a product using your brand. Critique loops catch issues before they ship.

1. /gsp:project-brief — Scope what you're building

Define your project through guided Q&A — what it does, who it's for, what screens it needs. The brief that guides everything downstream.

Creates: .design/projects/{project}/BRIEF.md

2. /gsp:project-research — Patterns and precedents

Deep research into UX patterns, competitor approaches, and technical considerations for your specific project.

Creates: .design/projects/{project}/research/

3. /gsp:project-design — Screens and flows

Design your UI screens and interaction flows following Apple HIG patterns. Layout, navigation, states, responsive behavior — documented to build from.

Creates: .design/projects/{project}/design/

4. /gsp:project-critique — Critique + accessibility

Two parallel audits: structured design critique using Nielsen's 10 usability heuristics, and a WCAG 2.2 AA accessibility check. If issues surface, loop back and fix before building.

Creates: .design/projects/{project}/critique/

5. /gsp:project-build — Designs to code

Translate reviewed designs into production-ready frontend code — written directly into your codebase. Components, styles, interactions built from your design system and tokens.

Creates: Components and styles in your codebase

6. /gsp:project-review — QA against designs

Validate what was built against the original design intent. Catches drift between design decisions and implementation.

Creates: .design/projects/{project}/review/

Commands

Entry

Branding

Project

Utility

Agents

GSP ships with 11 specialized agents, each modeled after a real design discipline:

Agents are thin stubs (~12 lines) at session start — full methodology loads on-demand from skill methodology/ directories when spawned. Each agent gets its own context window for focused creative/technical work.

AI Coding Tool Support

GSP works across all major AI coding tools. The installer converts Claude Code's native format into each runtime's expected format.

Runtime directories

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.

Install

npx get-shit-pretty

The installer prompts you to choose:

1. Runtime — Claude Code, OpenCode, Gemini, Codex, or all
2. Location — Global (all projects) or local (current project only)

# Claude Code
npx get-shit-pretty --claude --global
npx get-shit-pretty --claude --local

# OpenCode
npx get-shit-pretty --opencode --global

# Gemini CLI
npx get-shit-pretty --gemini --global

# Codex CLI
npx get-shit-pretty --codex --global

# All runtimes
npx get-shit-pretty --all --global

npx get-shit-pretty --claude --global --uninstall
npx get-shit-pretty --opencode --global --uninstall
npx get-shit-pretty --gemini --global --uninstall
npx get-shit-pretty --codex --global --uninstall

# From the repo root:
node bin/install.js --claude --local

Symlinks skills and agents to .claude/ — edits to gsp/ are reflected immediately.

Repo Structure

get-shit-pretty/
├── bin/
│   └── install.js         Multi-runtime installer
├── scripts/               Hook scripts and utilities
├── gsp/                   Source of truth for all content
│   ├── agents/            11 subagents (gsp-*.md stubs)
│   ├── skills/            34 skills (*/SKILL.md + methodology/ siblings)
│   ├── hooks/             Hooks (hooks.json)
│   ├── templates/         Config, state, brief, roadmap templates
│   └── references/        Shared reference material
├── dev/                   Internal dev tools (not installed)
│   ├── skills/            Dev-only skills (gsp-audit, gsp-runtime-compat)
│   └── scripts/           Test suite (audit-tests.sh)
├── package.json           npm package config
├── VERSION                Single source for version string
└── CLAUDE.md              AI agent instructions for this repo

The installer reads from gsp/ and writes to each runtime's config directory.

Contributing

Edit source under gsp/ — never edit inside .claude/ or other runtime dirs directly. For local development, the installer creates symlinks so changes reflect immediately without reinstalling.

# Install locally with symlinks
node bin/install.js --claude --local

# Run the integrity test suite
bash dev/scripts/audit-tests.sh

See CLAUDE.md for editing rules, key files, and dev tool setup.

Requirements

• An AI coding tool: Claude Code, OpenCode, Gemini CLI, or Codex CLI

License

MIT License. See LICENSE for details.