get-shit-pretty 0.1.1 → 0.3.0

package/README.md

@@ -1,69 +1,173 @@
-# GSP — Get Shit Pretty
+<div align="center">
 
-A design engineering system for AI coding tools. GSP guides you through a phased design pipeline — from research to launch — using specialized prompts and agents.
+# GET SHIT PRETTY
 
-## Install
+**Design engineering for AI coding tools.**
+
+**Research, brand, design system, UI, specs, review, build, launch — from your terminal.**
+
+[![npm version](https://img.shields.io/npm/v/get-shit-pretty?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-pretty)
+[![npm downloads](https://img.shields.io/npm/dm/get-shit-pretty?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-pretty)
+[![GitHub stars](https://img.shields.io/github/stars/jubscodes/get-shit-pretty?style=for-the-badge&logo=github&color=181717)](https://github.com/jubscodes/get-shit-pretty)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+
+<br>
 
 ```bash
 npx get-shit-pretty
 ```
 
-Or with flags:
+**Works on Mac, Windows, and Linux.**
 
-```bash
-# Claude Code (global)
-npx get-shit-pretty --claude --global
+<br>
 
-# All runtimes
-npx get-shit-pretty --all --global
+*"Vibe-coded apps work. They also all look the same. GSP fixes that."*
 
-# Uninstall
-npx get-shit-pretty --claude --global --uninstall
+<br>
+
+[Why GSP Exists](#why-gsp-exists) · [How It Works](#how-it-works) · [Commands](#commands) · [Agents & Prompts](#agents--prompts) · [AI Tool Support](#ai-coding-tool-support)
+
+</div>
+
+---
+
+## 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
+
+### 1. Start a Project
+
+```
+/gsp:new-project
 ```
 
-<details>
-<summary>Legacy install (bash)</summary>
+Answer questions about your product — what it does, who it's for, the vibe you're going for. GSP creates a design brief that guides everything downstream.
+
+**Creates:** `.design/BRIEF.md`
+
+---
+
+### 2. Research
 
-```bash
-git clone https://github.com/jubscodes/get-shit-pretty.git ~/get-shit-pretty
-cd ~/get-shit-pretty
-chmod +x install.sh
-./install.sh
+```
+/gsp:research
 ```
 
-</details>
+Analyzes design trends in your space — competitor patterns, emerging styles, what's working and what's not. Start with context, not guesses.
 
-## AI Coding Tool Support
+**Creates:** `.design/research/TRENDS.md`
 
-| Feature | Claude Code | OpenCode | Gemini CLI | Codex CLI |
-|---------|:-----------:|:--------:|:----------:|:---------:|
-| Slash commands | /gsp:command | /gsp-command | /gsp:command | $gsp-command |
-| Agents | Yes | Yes | Yes | Yes |
-| Prompts bundle | Yes | Yes | Yes | Yes |
-| Templates bundle | Yes | Yes | Yes | Yes |
-| References bundle | Yes | Yes | Yes | Yes |
-| Statusline | Yes | — | — | — |
-| Interactive install | Yes | Yes | Yes | Yes |
-| Global install | ~/.claude | ~/.config/opencode | ~/.gemini | ~/.codex |
-| Local install | .claude/ | .opencode/ | .gemini/ | .codex/ |
+---
 
-## Commands
+### 3. Brand
 
-| Command | Description |
-|---------|-------------|
-| `/gsp:new-project` | Initialize a design brief through guided Q&A |
-| `/gsp:research` | Analyze design trends for your industry |
-| `/gsp:brand` | Create brand identity (strategy, logo, color, type) |
-| `/gsp:system` | Build design system foundations + tokens |
-| `/gsp:design` | Design UI/UX screens and flows |
-| `/gsp:spec` | Generate Figma-ready specifications |
-| `/gsp:review` | Design critique + accessibility audit |
-| `/gsp:build` | Translate designs to production code |
-| `/gsp:launch` | Create marketing campaign assets |
-| `/gsp:progress` | Check project status — "How pretty are we?" |
-| `/gsp:help` | Show command reference |
+```
+/gsp:brand
+```
+
+Builds your complete identity — positioning, personality, logo directions, color palette, typography system. Your brand, not a default theme.
+
+**Creates:** `.design/brand/IDENTITY.md`
+
+---
+
+### 4. Design System
+
+```
+/gsp:system
+```
+
+Translates your brand into a functional design system — color scales, type scales, spacing, component foundations, and design tokens. Your system, in code.
+
+**Creates:** `.design/system/SYSTEM.md`, `tokens.json`
+
+---
+
+### 5. UI Design
+
+```
+/gsp:design
+```
+
+Designs your screens and interaction flows following Apple HIG patterns. Layout, navigation, states, responsive behavior — all documented with enough detail to build from.
+
+**Creates:** `.design/screens/SCREENS.md`
+
+---
+
+### 6. Implementation Specs
+
+```
+/gsp:spec
+```
+
+Maps your screen designs to your implementation target — shadcn/ui components, React Native Reusables, an existing design system, Figma specs, or lightweight code specs. Bridges design decisions to whatever UI framework your project uses.
+
+**Creates:** `.design/specs/SPECS.md`
+
+---
+
+### 7. Review
+
+```
+/gsp:review
+```
+
+Two parallel agents audit your designs:
+- **Design Critique** — Structured critique using Nielsen's 10 usability heuristics
+- **Accessibility Audit** — WCAG 2.2 AA compliance check
+
+If issues are found, loop back to fix before building.
+
+**Creates:** `.design/review/CRITIQUE.md`, `ACCESSIBILITY.md`
 
-## Pipeline
+---
+
+### 8. Build
+
+```
+/gsp:build
+```
+
+Translates reviewed designs into production-ready frontend code. Components, styles, interactions — built from your design system and tokens, not generic defaults.
+
+**Creates:** `.design/build/CODE.md`, `components/`
+
+---
+
+### 9. Launch
+
+```
+/gsp:launch
+```
+
+Creates marketing campaign assets — landing page copy, social media content, launch materials. Your product ships with a story, not just code.
+
+**Creates:** `.design/launch/CAMPAIGN.md`
+
+---
+
+### The Full Pipeline
 
 ```
 /gsp:new-project → BRIEF.md
@@ -76,7 +180,7 @@ chmod +x install.sh
        ↓
 /gsp:design      → .design/screens/SCREENS.md
        ↓
-/gsp:spec        → .design/specs/FIGMA-SPECS.md
+/gsp:spec        → .design/specs/SPECS.md
        ↓
 /gsp:review      → .design/review/CRITIQUE.md + ACCESSIBILITY.md
        ↓  (loop back if issues found)
@@ -87,25 +191,135 @@ chmod +x install.sh
 
 All artifacts live in `.design/` within your project directory.
 
-## Prompts
+---
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/gsp:new-project` | Initialize a design brief through guided Q&A |
+| `/gsp:research` | Analyze design trends for your industry |
+| `/gsp:brand` | Create brand identity (strategy, logo, color, type) |
+| `/gsp:system` | Build design system foundations + tokens |
+| `/gsp:design` | Design UI/UX screens and flows |
+| `/gsp:spec` | Generate implementation specifications |
+| `/gsp:review` | Design critique + accessibility audit |
+| `/gsp:build` | Translate designs to production code |
+| `/gsp:launch` | Create marketing campaign assets |
+| `/gsp:progress` | Check project status |
+| `/gsp:help` | Show command reference |
+
+---
+
+## Agents & Prompts
+
+GSP ships with 9 specialized agents, each modeled after a real design discipline:
+
+| Agent | Role |
+|-------|------|
+| **Design System Architect** | Complete design systems (Apple Principal Designer level) |
+| **Brand Identity Creator** | Full brand identities (Pentagram Creative Director level) |
+| **UI/UX Pattern Master** | App UI design following Apple HIG |
+| **Marketing Asset Factory** | Campaign asset libraries |
+| **Implementation Spec Engineer** | Implementation specifications for any UI target |
+| **Design Critique Partner** | Structured critiques using Nielsen's 10 heuristics |
+| **Design Trend Synthesizer** | Industry trend analysis and competitive research |
+| **Accessibility Auditor** | WCAG 2.2 AA compliance auditing |
+| **Design-to-Code Translator** | Design to production-ready frontend code |
+
+Each agent has deep reference material — Apple HIG patterns, Nielsen's heuristics, WCAG checklists, design token standards — baked into its prompts.
+
+---
+
+## AI Coding Tool Support
+
+GSP works across all major AI coding tools:
+
+| Feature | Claude Code | OpenCode | Gemini CLI | Codex CLI |
+|---------|:-----------:|:--------:|:----------:|:---------:|
+| Slash commands | `/gsp:command` | `/gsp-command` | `/gsp:command` | `$gsp-command` |
+| Agents | Yes | Yes | Yes | Yes |
+| Prompts | Yes | Yes | Yes | Yes |
+| Templates | Yes | Yes | Yes | Yes |
+| References | Yes | Yes | Yes | Yes |
+| Statusline | Yes | — | — | — |
+| Global install | `~/.claude` | `~/.config/opencode` | `~/.gemini` | `~/.codex` |
+| Local install | `.claude/` | `.opencode/` | `.gemini/` | `.codex/` |
+
+---
+
+## Install
+
+```bash
+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)
+
+<details>
+<summary><strong>Non-interactive install</strong></summary>
+
+```bash
+# Claude Code
+npx get-shit-pretty --claude --global
+npx get-shit-pretty --claude --local
 
-GSP bundles 9 specialized design prompts:
+# OpenCode
+npx get-shit-pretty --opencode --global
 
-1. **Design System Architect** — Complete design systems (Apple Principal Designer)
-2. **Brand Identity Creator** — Full brand identities (Pentagram Creative Director)
-3. **UI/UX Pattern Master** — App UI design (Apple HIG)
-4. **Marketing Asset Factory** — Campaign asset libraries
-5. **Figma Auto-Layout Expert** — Figma-ready specifications
-6. **Design Critique Partner** — Structured critiques (Nielsen's 10)
-7. **Design Trend Synthesizer** — Industry trend analysis
-8. **Accessibility Auditor** — WCAG 2.2 AA compliance
-9. **Design-to-Code Translator** — Design to production code
+# Gemini CLI
+npx get-shit-pretty --gemini --global
+
+# Codex CLI
+npx get-shit-pretty --codex --global
+
+# All runtimes
+npx get-shit-pretty --all --global
+```
+
+</details>
+
+<details>
+<summary><strong>Uninstall</strong></summary>
+
+```bash
+npx get-shit-pretty --claude --global --uninstall
+npx get-shit-pretty --opencode --global --uninstall
+npx get-shit-pretty --codex --global --uninstall
+```
+
+</details>
+
+<details>
+<summary><strong>Legacy install (bash)</strong></summary>
+
+```bash
+git clone https://github.com/jubscodes/get-shit-pretty.git ~/get-shit-pretty
+cd ~/get-shit-pretty
+chmod +x install.sh
+./install.sh
+```
+
+</details>
+
+---
 
 ## Requirements
 
 - An AI coding tool: [Claude Code](https://claude.ai/claude-code), [OpenCode](https://opencode.ai), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Codex CLI](https://github.com/openai/codex)
-- GitHub CLI (`gh`) for repo creation
+
+---
 
 ## License
 
-MIT
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+
+**Your code works. GSP makes it yours.**
+
+</div>

package/agents/gsp-brand-strategist.md

@@ -19,10 +19,11 @@ Use trend insights (if available) to ensure the identity feels current while rem
 1. **Absorb context** — Read BRIEF.md for company, industry, audience, personality. Read TRENDS.md for market positioning opportunities.
 2. **Define strategy** — Brand story, archetype, voice matrix, messaging hierarchy
 3. **Explore visual directions** — 3 distinct logo concepts that each express the strategy differently
-4. **Build color system** — Full color palette with Hex, RGB, Pantone, CMYK, contrast ratios, dark mode, and strategic rationale
-5. **Define typography** — Primary and secondary typefaces with scale and usage rules
-6. **Specify imagery** — Photography, illustration, and iconography style
-7. **Apply** — Show brand in context across key applications
+4. **Build color system** — Define primary, secondary, and accent hex colors with strategic rationale
+5. **Generate palettes** — Use the [tints.dev](https://tints.dev) API by [Simeon Griggs](https://github.com/SimeonGriggs/tints.dev) to generate 11-stop Tailwind palettes for each brand color. Fetch `https://tints.dev/api/{name}/{hex}` (hex without #). Store results in `.design/brand/palettes.json` with OKLCH values (stops 50–950). Include Hex, RGB, Pantone, CMYK, contrast ratios, and dark mode mapping in IDENTITY.md.
+6. **Define typography** — Primary and secondary typefaces with scale and usage rules
+7. **Specify imagery** — Photography, illustration, and iconography style
+8. **Apply** — Show brand in context across key applications
 
 ## Quality Standards
 - Every decision needs strategic rationale ("We chose X because Y")

package/agents/gsp-critic.md

@@ -53,3 +53,57 @@ Write critique to `.design/review/CRITIQUE.md`:
 8. **Alternative Directions** — 2 redesign approaches with descriptions
 9. **What Works Well** — Specific strengths to preserve
 </output>
+
+<chunked-exports>
+## Chunked Exports
+
+After writing CRITIQUE.md, generate an agent-consumable fix list.
+
+### Output
+
+Write `.design/review/exports/review-fixes.md` (~50-100 lines):
+
+```markdown
+# Review Fixes
+
+> Phase: Review | Source: [CRITIQUE.md](../CRITIQUE.md) | Generated: {DATE}
+
+---
+
+## Critical Fixes
+
+- **[Screen/Component]:** {Issue} → {Concrete fix}
+
+## Important Fixes
+
+- **[Screen/Component]:** {Issue} → {Concrete fix}
+
+---
+
+## Related
+
+- [CRITIQUE.md](../CRITIQUE.md) — full critique with heuristic scores
+- [accessibility-fixes.md](./accessibility-fixes.md) — WCAG violations
+```
+
+### Rules
+
+- Only include Critical and Important severity — skip Polish items
+- Every fix must name the specific screen or component affected
+- Every fix must include a concrete remediation (not just "improve X")
+- Preserve exact issue descriptions from CRITIQUE.md
+- See `references/chunk-format.md` for standard header, footer, naming, and size rules
+
+### Update INDEX.md
+
+Replace `<!-- BEGIN:review -->` … `<!-- END:review -->` in `.design/exports/INDEX.md` with:
+
+```markdown
+<!-- BEGIN:review -->
+| Section | File |
+|---------|------|
+| Review Fixes | [review-fixes.md](../review/exports/review-fixes.md) |
+| Accessibility Fixes | [accessibility-fixes.md](../review/exports/accessibility-fixes.md) |
+<!-- END:review -->
+```
+</chunked-exports>

package/agents/gsp-design-engineer.md

@@ -8,15 +8,24 @@ color: magenta
 <role>
 You are a GSP design engineer spawned by `/gsp:build`.
 
-Act as a Vercel Design Engineer. Your job is to convert the Figma specifications and design system into production-ready frontend code — components, layouts, accessibility, animations, and styling.
+Act as a Vercel Design Engineer. Your job is to convert the implementation specifications and design system into production-ready frontend code — components, layouts, accessibility, animations, and styling.
+
+You adapt your approach based on the `implementation_target`:
+- **`shadcn`** — Use shadcn/ui primitives, install via `npx shadcn@latest add`, extend with custom variants
+- **`rn-reusables`** — Use React Native Reusables, install via `npx @react-native-reusables/cli add`, configure NativeWind
+- **`existing`** — Build on the existing design system in the codebase, follow its patterns
+- **`figma` / `code`** — Derive component structure from specs or screen designs
+- **`skip` (no SPECS.md)** — Build directly from SCREENS.md + SYSTEM.md, derive component architecture yourself
 
 Write real, copy-paste-ready code. Not pseudocode. Not "implementation left as exercise." Production code.
+
+**Chunk-aware mode:** When chunked exports are provided instead of full monoliths (screen chunks, spec chunks, component chunks), work with the focused context. Do not request additional monolith files unless the chunks are insufficient for the task. This keeps your context lean and focused on the specific screen being built.
 </role>
 
 <methodology>
 ## Translation Process
 
-1. **Map component hierarchy** — From specs, define the component tree with props, state, and data flow
+1. **Map component hierarchy** — From specs (or screens if spec was skipped), define the component tree with props, state, and data flow
 2. **Implement foundations** — Design tokens as CSS variables or Tailwind config, theme setup, global styles
 3. **Build components** — One file per component with full implementation
 4. **Add accessibility** — ARIA roles, keyboard handlers, focus management, screen reader support