get-shit-pretty 0.7.0 → 0.7.3

package/README.md

@@ -25,7 +25,7 @@ npx get-shit-pretty
 
 <br>
 
-[Why GSP Exists](#why-gsp-exists) · [How It Works](#how-it-works) · [Branding Diamond](#-diamond-1--branding) · [Project Diamond](#-diamond-2--project) · [Commands](#commands) · [Agents](#agents) · [AI Tool Support](#ai-coding-tool-support)
+[Why GSP Exists](#why-gsp-exists) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Style Presets](#style-presets) · [Expertise Skills](#expertise-skills) · [Skills](#skills) · [Agents](#agents) · [Architecture](#architecture) · [AI Tool Support](#ai-coding-tool-support) · [Contributing](#contributing)
 
 </div>
 
@@ -35,21 +35,34 @@ npx get-shit-pretty
 
 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.
+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.
+Both disciplines. Same pipeline. Same environment. The missing half of the bridge.
 
-The missing half of the bridge.
+---
+
+## Quick Start
+
+```bash
+# 1. Install
+npx get-shit-pretty
+
+# 2. Define your brand — or skip with a style preset
+/gsp-brand-brief                    # guided brand definition
+/gsp-style cyberpunk                # instant tokens from 35 presets
+
+# 3. Build something
+/gsp-project-brief                  # scope your project
+/gsp-project-build                  # parallel agents build it
+```
+
+Or run `/gsp-start` — it detects your workspace state and routes you forward.
 
 ---
 
@@ -58,27 +71,72 @@ The missing half of the bridge.
 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 ─────┘      │
-                                           └──────────────────────────────┘
-                                                      ↓
-                                                  /gsp:launch (optional)
+/gsp-start → picks up where you left off, routes you forward
+
+       ◆ Diamond 1 — Branding                    ◆ Diamond 2 — Project
+  ┌──────────────────────────────┐         ┌──────────────────────────────┐
+  │  brand-brief                 │         │  project-brief               │
+  │    ↓                         │         │    ↓                         │
+  │  brand-research              │         │  project-research            │
+  │    ↓                         │         │    ↓                         │
+  │  brand-strategy              │         │  project-design              │
+  │    (includes voice           │         │    ↓                         │
+  │     and messaging)           │         │  project-critique ←──┐      │
+  │    ↓                         │         │    ↓            loop │      │
+  │  brand-identity              │         │  project-build       │      │
+  │    (4 expertise skills       │         │    ↓                 │      │
+  │     run in parallel)         │         │  project-review ─────┘      │
+  │    ↓                         │         └──────────────────────────────┘
+  │  brand-guidelines            │
+  └──────────────────────────────┘
+```
+
+All artifacts live in `.design/` within your project directory. State tracked in `STATE.md` with automatic session recovery.
+
+---
+
+## Style Presets
+
+35 built-in design styles. Fuzzy-matched — describe what you want, get production-ready tokens.
+
+```bash
+/gsp-style cyberpunk                # exact match
+/gsp-style "something dark and techy"  # fuzzy → cyberpunk, terminal, modern-dark
 ```
 
-All artifacts live in `.design/` within your project directory.
+| Category | Presets |
+|----------|---------|
+| **Industrial** | nothing |
+| **Minimal** | swiss-minimalist, flat-design, monochrome, minimal-dark |
+| **Modern** | professional, saas, enterprise, fluent, material, modern-dark, glassmorphism, liquid-glass |
+| **Creative** | neubrutalism, cyberpunk, maximalism, bold-typography, playful-geometric, sketch, kinetic |
+| **Elegant** | luxury, art-deco, academia, humanist-literary |
+| **Organic** | botanical, organic |
+| **Editorial** | newsprint |
+| **Nostalgic** | retro, vaporwave |
+| **Tactile** | claymorphism, neumorphism, industrial |
+| **Tech** | terminal, web3 |
+| **Geometric** | bauhaus |
+
+Each preset produces design tokens (W3C format), `STYLE.md`, and foundation chunks. Skip the full branding diamond when you just need a solid starting point.
+
+---
+
+## Expertise Skills
+
+Seven standalone design tools that work independently or as part of the pipeline.
+
+| Skill | What it does |
+|-------|--------------|
+| `/gsp-color` | Palettes, contrast, semantic mapping, dark mode (OKLCH) |
+| `/gsp-typography` | Scale, pairing, fluid type, vertical rhythm |
+| `/gsp-visuals` | Imagery, 3D, video, textures, surface treatments |
+| `/gsp-icons` | Library selection, sizing, containers, custom SVG direction |
+| `/gsp-logo` | Concepts, variations, usage rules, clear space |
+| `/gsp-accessibility` | Quick contrast checks and token WCAG audits (inline) |
+| `/gsp-style` | Apply a preset — tokens without the full branding diamond |
+
+These are the knowledge owners in GSP's two-layer architecture. Pipeline skills invoke them during orchestration, but you can run any of them directly for standalone design decisions.
 
 ---
 
@@ -86,31 +144,37 @@ All artifacts live in `.design/` within your project directory.
 
 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.
+> **Already have a brand?** Run `/gsp-start` and choose "evolve existing brand" — it sets up the `.design/` structure, then routes you to `/gsp-brand-audit` to assess what you have before evolving it.
+
+#### 1. `/gsp-brand-brief` — Define your brand
 
-#### 1. `/gsp:brand-research` — Market landscape
+Guided Q&A — who it's for, why it exists, what it should feel like. The brief that feeds every downstream phase.
+
+**Creates:** `.design/branding/{brand}/BRIEF.md`
+
+#### 2. `/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
+#### 3. `/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
+#### 4. `/gsp-brand-identity` — How you look
 
-Create your visual identity — logo directions, color palette, typography system, imagery style. Design decisions, not decoration.
+Create your visual identity — logo directions, color palette, typography system, imagery style. Four expertise skills (logo, color, typography, visuals) run in parallel for speed.
 
 **Creates:** `.design/branding/{brand}/identity/`
 
-#### 4. `/gsp:brand-patterns` — Your design system
+#### 5. `/gsp-brand-guidelines` — Your design system
 
-Translate your brand into tokens, components, and a living design system. Everything codified and ready to build with.
+Operationalize your brand — assemble tokens, `STYLE.md`, component mapping, and guidelines. Everything codified and ready to build with.
 
-**Creates:** `.design/branding/{brand}/patterns/`
+**Creates:** `.design/branding/{brand}/system/`
 
 ---
 
@@ -118,121 +182,210 @@ Translate your brand into tokens, components, and a living design system. Everyt
 
 Design and build a product using your brand. Critique loops catch issues before they ship.
 
-#### 1. `/gsp:project-brief` — Scope what you're building
+#### 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
+#### 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
+#### 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
+#### 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.
+Two parallel audits: structured design critique (Nielsen's 10 heuristics + brand contract scoring) and WCAG 2.2 AA accessibility check. Mixed-model assignment — critic runs on your model while the accessibility auditor runs on Sonnet, eliminating rate-limit competition. Brand constraint violations auto-fail.
 
 **Creates:** `.design/projects/{project}/critique/`
 
-#### 5. `/gsp:project-build` — Designs to code
+#### 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.
+Seven-phase parallel build pipeline: scaffold, foundations, review, components (parallel wave), screens (parallel wave), extraction review, finalize. Round-robin model assignment (Opus/Sonnet) distributes rate-limit pressure across agents. ~47% faster than sequential builds.
 
 **Creates:** Components and styles in your codebase
 
-#### 6. `/gsp:project-review` — QA against designs
+#### 6. `/gsp-project-review` — QA against designs
 
-Validate what was built against the original design intent. Catches drift between design decisions and implementation.
+Validate what was built against the original design intent. Catches drift between design decisions and implementation. Pass/Conditional/Fail verdict.
 
 **Creates:** `.design/projects/{project}/review/`
 
 ---
 
-### Optional: `/gsp:launch`
-
-Create marketing campaign assets — landing page copy, social media content, launch materials. Your product ships with a story, not just code.
-
-**Creates:** `.design/projects/{project}/launch/`
-
----
-
-## Commands
+## Skills
 
 ### Entry
 
-| Command | What it does |
-|---------|--------------|
-| `/gsp:start` | Pick up where you left off — routes you forward |
-| `/gsp:progress` | Check project status |
-| `/gsp:help` | Show command reference |
+| Skill | What it does |
+|-------|--------------|
+| `/gsp-start` | Pick up where you left off — routes you forward |
+| `/gsp-progress` | Check project status |
+| `/gsp-help` | Show skill reference |
 
 ### Branding
 
-| Command | What it does |
-|---------|--------------|
-| `/gsp:brand-audit` | Audit an existing brand before evolving it |
-| `/gsp:brand-research` | Research market, audience, competitors |
-| `/gsp:brand-strategy` | Define archetype, positioning, personality, voice, messaging |
-| `/gsp:brand-identity` | Create visual identity — logo, color, type |
-| `/gsp:brand-patterns` | Build design system — tokens, components |
-| `/gsp:brand-refine` | Surgical token and palette adjustments mid-project |
+| Skill | What it does |
+|-------|--------------|
+| `/gsp-brand-brief` | Define your brand through guided Q&A |
+| `/gsp-brand-audit` | Audit an existing brand before evolving it |
+| `/gsp-brand-research` | Research market, audience, competitors |
+| `/gsp-brand-strategy` | Define archetype, positioning, personality, voice, messaging |
+| `/gsp-brand-identity` | Create visual identity — logo, color, type |
+| `/gsp-brand-guidelines` | Build design system — tokens, STYLE.md, components |
+| `/gsp-brand-refine` | Surgical token and palette adjustments mid-project |
+| `/gsp-brand-sync` | Sync brand to match a project's shipped state |
 
 ### Project
 
-| Command | What it does |
-|---------|--------------|
-| `/gsp:project-brief` | Scope through guided Q&A |
-| `/gsp:project-research` | UX patterns, competitor analysis |
-| `/gsp:project-design` | Design screens and interaction flows |
-| `/gsp:project-critique` | Nielsen's heuristics + WCAG 2.2 AA audit |
-| `/gsp:project-build` | Translate designs to production code |
-| `/gsp:project-review` | QA validation against designs |
-| `/gsp:launch` | Marketing campaign assets |
-
-### Utility
-
-| Command | What it does |
-|---------|--------------|
-| `/gsp:accessibility-audit` | Full WCAG 2.2 AA accessibility audit |
-| `/gsp:add-reference` | Add reference material to a project |
-| `/gsp:doctor` | Check project health |
-| `/gsp:update` | Update GSP to latest version |
-| `/gsp:art` | Craft ASCII art interactively |
-| `/gsp:pretty` | Surprise ASCII art in the terminal |
+| Skill | What it does |
+|-------|--------------|
+| `/gsp-project-brief` | Scope through guided Q&A |
+| `/gsp-project-research` | UX patterns, competitor analysis |
+| `/gsp-project-design` | Design screens and interaction flows |
+| `/gsp-project-critique` | Nielsen's heuristics + WCAG 2.2 AA audit |
+| `/gsp-project-build` | Translate designs to production code |
+| `/gsp-project-review` | QA validation against designs |
+
+### Expertise
+
+| Skill | What it does |
+|-------|--------------|
+| `/gsp-color` | Design color systems — palettes, contrast, dark mode |
+| `/gsp-typography` | Design type systems — scale, pairing, fluid type |
+| `/gsp-visuals` | Define visual direction — imagery, textures, 3D |
+| `/gsp-icons` | Design icon systems — library, sizing, custom SVG |
+| `/gsp-logo` | Design logo directions — concepts, variations, rules |
+| `/gsp-accessibility` | Quick contrast checks and token WCAG audits |
+| `/gsp-style` | Apply a style preset — tokens without the full diamond |
+
+### Utilities
+
+| Skill | What it does |
+|-------|--------------|
+| `/gsp-design-system` | Scan and document existing design system state |
+| `/gsp-scaffold` | Deterministic stack setup — install deps, create configs, verify build |
+| `/gsp-accessibility-audit` | Full WCAG 2.2 AA accessibility audit |
+| `/gsp-add-reference` | Add reference material to a project |
+| `/gsp-doctor` | Check project health |
+| `/gsp-update` | Update GSP to latest version |
+| `/gsp-art` | Craft ASCII art interactively |
+| `/gsp-pretty` | Surprise ASCII art in the terminal |
 
 ---
 
 ## Agents
 
-GSP ships with 15 specialized agents, each modeled after a real design discipline:
+GSP ships 11 specialized agents, each modeled after a real design discipline:
 
 | Agent | Role |
 |-------|------|
 | **Brand Strategist** | Brand strategy using Kapferer Prism, archetypes, positioning, voice, and messaging |
-| **Identity Designer** | Visual identity — logo, color palettes, typography systems |
-| **Design System Architect** | Complete design systems — tokens, components, foundations |
+| **Brand Creative Director** | Visual identity — logo, color palettes, typography systems |
+| **Brand Engineer** | Design systems — tokens, components, foundations, guidelines |
 | **Brand Auditor** | Brand coherence assessment and evolution mapping |
-| **Trend Researcher** | Market landscape, competitor analysis, emerging patterns |
+| **Brand Researcher** | Market landscape, competitor analysis, emerging patterns |
 | **Project Researcher** | Deep UX patterns, competitor UX, technical approaches |
-| **Project Scoper** | Project scope through guided Q&A |
-| **UI/UX Designer** | Screen design and interaction flows following Apple HIG |
-| **Design Critic** | Structured critiques using Nielsen's 10 heuristics |
+| **Project Designer** | Screen design and interaction flows following Apple HIG |
+| **Project Critic** | Structured critiques using Nielsen's 10 heuristics |
+| **Project Builder** | Designs to production-ready frontend code |
+| **Project Reviewer** | QA validation — implementation against design intent |
 | **Accessibility Auditor** | WCAG 2.2 AA compliance auditing |
-| **Design-to-Code Builder** | Designs to production-ready frontend code |
-| **Deliverable Reviewer** | QA validation — implementation against design intent |
-| **Campaign Director** | Marketing campaign asset libraries |
-| **Codebase Scanner** | Tech stack detection and existing pattern inventory |
-| **ASCII Artist** | Terminal ASCII art — context-aware art generation |
 
-Each agent carries deep reference material — Apple HIG patterns, Nielsen's heuristics, WCAG checklists, design token standards — baked into its prompts.
+Agents are thin stubs (~12 lines) at session start — full methodology loads on-demand when spawned. Each agent gets its own context window for focused work.
+
+### Parallel execution
+
+Build phases spawn agents in parallel waves with round-robin model assignment:
+
+```
+Orchestrator
+  │
+  ├── Wave 1: Components (parallel)
+  │   ├── Agent A (Opus)   → Button, Card, Input
+  │   ├── Agent B (Sonnet) → Nav, Footer, Sidebar
+  │   └── Agent C (Opus)   → Hero, Modal, Toast
+  │   └── ✓ SubagentStop hooks verify each agent's output
+  │
+  └── Wave 2: Screens (parallel)
+      ├── Agent D (Sonnet) → Home
+      ├── Agent E (Opus)   → Dashboard
+      └── Agent F (Sonnet) → Settings
+      └── ✓ SubagentStop hooks verify each agent's output
+```
+
+Components build first so screens can compose from them. Mixed-model assignment distributes rate-limit pressure — no single model gets overloaded.
+
+---
+
+## Architecture
+
+### Two-layer skills
+
+```
+┌─────────────────────────────────────────────────┐
+│  Pipeline Skills (orchestrators)                │
+│  brand-brief → research → strategy →            │
+│  identity → guidelines                          │
+│  project-brief → research → design →            │
+│  critique → build → review                      │
+│                                                 │
+│  ┌─────────────────────────────────────────┐    │
+│  │  Expertise Skills (knowledge owners)    │    │
+│  │  color · typography · visuals · icons   │    │
+│  │  logo · accessibility · style           │    │
+│  │  ← invoked by pipeline OR standalone    │    │
+│  └─────────────────────────────────────────┘    │
+│                                                 │
+│  Utilities                                      │
+│  start · progress · help · doctor · scaffold    │
+│  art · pretty · update                          │
+└─────────────────────────────────────────────────┘
+```
+
+Pipeline skills own workflow — state management, phase gates, agent spawning. Expertise skills own domain knowledge — palettes, type scales, visual direction. Pipeline skills read from expertise skills, never the other way around. No domain knowledge is duplicated across skills.
+
+### `.design/` artifacts
+
+Every phase writes structured output to `.design/`:
+
+```
+.design/
+├── branding/{brand}/
+│   ├── BRIEF.md, STATE.md, config.json
+│   ├── discover/        ← brand-research
+│   ├── strategy/        ← brand-strategy (includes voice + messaging)
+│   ├── identity/        ← brand-identity (color, type, logo, imagery)
+│   └── system/          ← brand-guidelines (tokens, STYLE.md, components)
+│
+├── projects/{project}/
+│   ├── BRIEF.md, STATE.md, config.json
+│   ├── research/        ← project-research
+│   ├── design/          ← project-design (screens, flows, preview.html)
+│   ├── critique/        ← project-critique (Nielsen + WCAG scores)
+│   ├── build/           ← project-build (logs, status, manifests)
+│   └── review/          ← project-review (acceptance report, verdict)
+│
+└── CHANGELOG.md         ← aggregated across all projects
+```
+
+### Hooks and integrations
+
+- **SessionStart** — context recovery script re-injects active brand/project state on session resume
+- **SubagentStop** — 10 verification hooks confirm deliverables after every agent completes
+- **PostToolUse** — lint-check on builder agent edits
+- **Statusline** — live display of model, phase, prettiness score, context usage (Claude Code)
+- **Figma MCP** — read designs directly from Figma into your pipeline
+- **GitHub MCP** — issues and PRs accessible from within the pipeline
+
+Zero production dependencies. The installer and all scripts use pure Node.js builtins.
 
 ---
 
@@ -242,12 +395,12 @@ GSP works across all major AI coding tools. The installer converts Claude Code's
 
 | Feature | Claude Code | OpenCode | Gemini CLI | Codex CLI |
 |---------|:-----------:|:--------:|:----------:|:---------:|
-| Skills | 30 | 30 | 30 | 30 |
-| Agents | 15 | 15 | 15 (experimental) | — |
-| Slash syntax | `/gsp:command` | `/gsp-command` | `/gsp:command` | `$gsp-command` |
-| Prompts + templates | Yes | Yes | Yes | Yes |
-| References | Yes | Yes | Yes | Yes |
+| Skills | 34 | 34 | 34 | 34 |
+| Agents | 11 | 11 | 11 (experimental) | — |
+| Slash syntax | `/gsp-command` | `/gsp-command` | `/gsp-command` | `$gsp-command` |
+| MCP servers | Figma + GitHub | — | — | — |
 | Statusline hooks | Yes | — | — | — |
+| Prompts + templates | Yes | Yes | Yes | Yes |
 
 ### Runtime directories
 
@@ -258,7 +411,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 (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/`. Codex does not support agent `.md` files.
 
 ---
 
@@ -308,14 +461,15 @@ npx get-shit-pretty --codex --global --uninstall
 </details>
 
 <details>
-<summary><strong>Local development</strong></summary>
+<summary><strong>Cherry-pick skills</strong></summary>
+
+Don't need the full pack? Pick individual skills via [The Agent Skills Directory](https://skills.sh/):
 
 ```bash
-# From the repo root:
-node bin/install.js --claude --local
+npx skills add jubscodes/get-shit-pretty
 ```
 
-Symlinks skills and agents to `.claude/` — edits to `gsp/` are reflected immediately.
+Select individual skills to install. Works with Claude Code, Cursor, Copilot, Gemini, and 20+ other agents.
 
 </details>
 
@@ -327,38 +481,61 @@ Symlinks skills and agents to `.claude/` — edits to `gsp/` are reflected immed
 get-shit-pretty/
 ├── bin/
 │   └── install.js         Multi-runtime installer
-├── scripts/               Hook scripts and utilities
+├── scripts/               Hook scripts (statusline, lint-check, context recovery)
 ├── gsp/                   Source of truth for all content
-│   ├── agents/            15 subagents (gsp-*.md)
-│   ├── skills/            38 skills (*/SKILL.md)
+│   ├── agents/            11 subagents (gsp-*.md stubs + methodology in skills)
+│   ├── skills/            34 skills (*/SKILL.md + domains/ + references/ + methodology/)
 │   ├── 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
+│   └── templates/         Config, state, brief, roadmap templates
+├── dev/                   Internal dev tools (not installed to runtimes)
+│   ├── skills/            Dev skills (gspdev-audit, gspdev-benchmark, gspdev-publish, ...)
+│   ├── scripts/           Test suite, token budget tools, benchmarking
+│   └── benchmarks/        Token budget snapshots per release
+├── package.json           npm package config (zero production dependencies)
 ├── 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.
+GSP's architecture is designed to be approachable. Each skill is a self-contained directory with a `SKILL.md` and optional sibling files (`methodology/`, `domains/`, `references/`). No complex build step — edit source, see results.
+
+### Where contributions are welcome
+
+- **New style presets** — add a `.yml` + `.md` to `gsp/skills/gsp-style/styles/` and register in `INDEX.yml`
+- **Expertise domain files** — expand design knowledge in `gsp/skills/gsp-color/domains/`, `gsp-typography/domains/`, etc.
+- **Runtime support** — improve installer compatibility for OpenCode, Gemini, Codex, or add new runtimes
+- **Test coverage** — the test suite has 65+ tests across 9 suites but always needs more
+- **Documentation** — skill descriptions, examples, tutorials
+
+### Local development
 
 ```bash
-# Install locally with symlinks
+# Clone and install with symlinks (edits to gsp/ reflect immediately)
 node bin/install.js --claude --local
 
-# Run the integrity test suite
+# Run the integrity test suite (9 suites: versions, contracts, installer, runtime, templates, prompts, unit, tokenbudget)
 bash dev/scripts/audit-tests.sh
+
+# Run a single suite
+bash dev/scripts/audit-tests.sh contracts
 ```
 
-See [CLAUDE.md](CLAUDE.md) for editing rules, key files, and dev tool setup.
+### Dev tools
+
+| Tool | Purpose |
+|------|---------|
+| `/gspdev-audit` | Pipeline integrity checker — contracts, installer, runtime compat |
+| `/gspdev-benchmark` | Token budget benchmarking — snapshots, comparisons, trajectory |
+| `/gspdev-housekeeping` | Drift catching — version mismatches, stale references |
+| `/gspdev-prompt-audit` | Semantic analysis of skills and agents |
+| `/gspdev-publish` | Release workflow — bump, changelog, audit, tag |
+
+See [CLAUDE.md](CLAUDE.md) for editing rules, architecture details, and key files.
+
+**Issues:** [github.com/jubscodes/get-shit-pretty/issues](https://github.com/jubscodes/get-shit-pretty/issues)
 
 ---
 

package/bin/install.js

@@ -1779,7 +1779,7 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
 
   ${c.bold}Get started:${c.reset}
     ${c.accent}${newCmd}${c.reset}     ${c.secondary}start here — brand, project, or both${c.reset}
-    ${c.accent}${helpCmd}${c.reset}      ${c.secondary}all commands${c.reset}
+    ${c.accent}${helpCmd}${c.reset}      ${c.secondary}all skills${c.reset}
 `);
   }
 }