get-shit-pretty 0.2.0 → 0.4.0

package/references/voice-tone.md

@@ -0,0 +1,193 @@
+# Voice & Tone Framework
+
+## Voice vs Tone
+
+**Voice** is the consistent personality of the brand. It doesn't change.
+**Tone** is how voice flexes based on context. It adapts to situation.
+
+Analogy: Your voice is who you are. Your tone is how you speak at a wedding vs a funeral vs a bar.
+
+---
+
+## 1. Voice Attribute Framework
+
+### Defining Voice Attributes
+Choose 3-5 attributes that describe how the brand communicates. Each attribute needs:
+
+1. **The attribute** (e.g., "Confident")
+2. **What it means** (e.g., "We speak with authority and certainty")
+3. **What it doesn't mean** (e.g., "Not arrogant, dismissive, or condescending")
+4. **Example** (e.g., "We know this works" vs "We're the best and everyone else is wrong")
+
+### Template
+
+| Attribute | Means | Doesn't Mean | Do | Don't |
+|-----------|-------|-------------|-----|-------|
+| Confident | Assured, knowledgeable | Arrogant, dismissive | "Here's the best approach" | "Obviously, anyone would know" |
+| Warm | Friendly, approachable | Overly casual, unprofessional | "We're here to help" | "Hey bestie! lol" |
+| Clear | Direct, simple | Dumbed down, patronizing | "Sign up in 3 steps" | "Even a child could do it" |
+
+### Common Voice Attribute Pairs
+- **Confident but not arrogant** — authority without superiority
+- **Playful but not childish** — fun without being unserious
+- **Expert but not elitist** — knowledgeable without excluding
+- **Warm but not saccharine** — friendly without being fake
+- **Bold but not aggressive** — daring without being off-putting
+- **Casual but not sloppy** — relaxed without being unprofessional
+- **Technical but not jargony** — precise without being inaccessible
+
+---
+
+## 2. Tone Spectrum
+
+### The 5 Spectrums
+
+Plot the brand's default position on each scale (1-5):
+
+```
+Formal    1 ─── 2 ─── 3 ─── 4 ─── 5  Casual
+Serious   1 ─── 2 ─── 3 ─── 4 ─── 5  Playful
+Authoritative 1 ─── 2 ─── 3 ─── 4 ─── 5  Friendly
+Technical 1 ─── 2 ─── 3 ─── 4 ─── 5  Simple
+Reserved  1 ─── 2 ─── 3 ─── 4 ─── 5  Enthusiastic
+```
+
+### Tone Shift by Context
+
+The default position shifts based on context. Map the range:
+
+| Context | Formal↔Casual | Serious↔Playful | Auth↔Friendly |
+|---------|:------------:|:--------------:|:-------------:|
+| Homepage | 3 | 3 | 3 |
+| Error message | 2 | 2 | 4 |
+| Success state | 3 | 4 | 4 |
+| Marketing email | 4 | 4 | 3 |
+| Legal/terms | 1 | 1 | 2 |
+| Social media | 4 | 5 | 5 |
+| Customer support | 2 | 2 | 5 |
+| Onboarding | 3 | 3 | 4 |
+| Empty state | 3 | 4 | 4 |
+| Loading state | 3 | 3 | 3 |
+
+---
+
+## 3. Voice Chart (Do / Don't)
+
+### Per-Attribute Chart
+
+For each voice attribute, provide concrete writing examples:
+
+**Attribute: Confident**
+
+| Do | Don't |
+|-----|-------|
+| "Your data is protected with 256-bit encryption" | "We think your data should be pretty safe" |
+| "Here's what we recommend" | "You might maybe want to consider" |
+| "This will save you 3 hours per week" | "This could potentially help save some time" |
+
+**Attribute: Warm**
+
+| Do | Don't |
+|-----|-------|
+| "Welcome back! Here's what's new" | "User session resumed. New items: 3" |
+| "We're here if you need anything" | "Submit a ticket for assistance" |
+| "Great choice!" | "Selection confirmed" |
+
+### Grammar & Style Rules
+- **Contractions:** Yes/No (Casual brands: yes. Formal: no.)
+- **Oxford comma:** Yes/No
+- **Exclamation marks:** Never / Sparingly / Freely
+- **Emoji:** Never / In social only / Everywhere
+- **First person:** "We" / "I" / Varies
+- **Addressing user:** "You" / Name / Formal
+- **Sentence length:** Short (avg 15 words) / Medium (20) / Long (25+)
+- **Jargon:** Avoid / Define on first use / Use freely (technical audience)
+
+---
+
+## 4. Messaging Matrix
+
+### Structure
+
+| Audience Segment | Key Message | Supporting Points | Tone Shift | Proof Point | Priority Channel |
+|-----------------|-------------|-------------------|-----------|------------|-----------------|
+| Primary persona | Core value prop for this segment | 2-3 supporting messages | How tone adapts | Evidence/social proof | Where to reach them |
+
+### Building the Matrix
+1. List audience segments from brand brief / personas
+2. For each segment, identify their primary motivation (what they care about most)
+3. Craft a key message that connects brand benefit to their motivation
+4. Add supporting points that build the case
+5. Note how tone shifts for this audience
+6. Provide proof points (data, testimonials, case studies)
+7. Identify the primary channel to reach them
+
+---
+
+## 5. Content Types Reference
+
+### Tone Guidelines by Content Type
+
+**Headlines:** Bold, concise, lead with benefit. 6-10 words.
+**Body copy:** Conversational, scannable, substantive. Short paragraphs.
+**CTAs:** Action-oriented, specific, urgent without pressure. 2-5 words.
+**Error messages:** Helpful, blame-free, solution-focused. State what happened + what to do.
+**Success messages:** Celebratory, brief, confirm what happened. Move forward.
+**Empty states:** Encouraging, instructional, not apologetic. Guide next action.
+**Tooltips:** Ultra-concise, single purpose, no fluff. One sentence.
+**Notifications:** Contextual, actionable, respectful of attention. Clear priority.
+**Onboarding:** Friendly, progressive, encouraging. Build confidence.
+**Legal:** Clear, plain language where possible. Accessible but accurate.
+
+---
+
+## 6. Brand Narrative Arc
+
+### The 4-Part Story Structure
+
+**1. Setup (Context)**
+Establish the world as it is. What's the status quo? What does the audience experience daily?
+
+**2. Tension (Problem)**
+Introduce the conflict. What's broken, frustrating, or missing? Why can't things stay the way they are?
+
+**3. Resolution (Solution)**
+Present the brand as the answer. How does it address the tension? What changes?
+
+**4. Transformation (Outcome)**
+Show the new reality. How is life different now? What has the audience gained?
+
+### Example: Slack
+1. **Setup:** Teams communicate through email, meetings, and scattered tools
+2. **Tension:** Information is lost, context-switching is exhausting, work feels fragmented
+3. **Resolution:** Slack brings all communication into organized channels with searchable history
+4. **Transformation:** Teams move faster, stay aligned, and actually enjoy working together
+
+---
+
+## 7. Naming Conventions
+
+### Naming Principles
+1. **Memorability:** Easy to say, spell, and remember
+2. **Meaning:** Communicates something about the brand or product
+3. **Distinctiveness:** Different from competitors
+4. **Scalability:** Works as the brand grows
+5. **Availability:** Domain, social handles, trademarks
+
+### Naming Approaches
+- **Descriptive:** Says what it does (General Electric, PayPal)
+- **Suggestive:** Hints at benefit (Pinterest, Slack)
+- **Abstract:** Invented word (Kodak, Xerox)
+- **Acronym:** Initials (IBM, BMW)
+- **Founder:** Named after creator (Ford, Chanel)
+- **Metaphor:** Borrowed meaning (Amazon, Apple)
+
+### Product/Feature Naming
+- Consistent pattern across products (Apple: i-prefix, Google: single words)
+- Hierarchy should be clear (Brand > Product > Feature > Sub-feature)
+- Internal names vs external names — keep them separate
+
+## Sources
+- Flaxton, K. (2020). *Voice and Tone in UX Writing*. A List Apart.
+- Content Design London. *Content Design* methodology.
+- NN/g. *Writing for the Web: Tone of Voice* research.

package/scripts/gsp-statusline.js

@@ -151,7 +151,7 @@ process.stdin.on('end', () => {
             (lParts[0] === iParts[0] && lParts[1] > iParts[1]) ||
             (lParts[0] === iParts[0] && lParts[1] === iParts[1] && lParts[2] > iParts[2]);
           if (isNewer) {
-            updateTag = ` \x1b[33m\u2191 v${latest}\x1b[0m`;
+            updateTag = ` \x1b[33m\u2191 /gsp:update\x1b[0m`;
           }
         }
       }

package/templates/branding/brief.md

@@ -0,0 +1,74 @@
+# Brand Brief
+
+## Brand
+- **Name:** {BRAND_NAME}
+- **Date:** {DATE}
+
+## Company
+- **Company name:** {COMPANY}
+- **Industry:** {INDUSTRY}
+- **Founded:** {YEAR}
+- **Size:** {SIZE}
+- **Existing brand?** {YES_NO}
+
+## Brand Mode
+- **Mode:** {new | evolve}
+- **Reason:** {why — market shift, audience change, product pivot, staleness}
+
+### Existing Brand State (evolve only)
+- **Current brand age:** {years}
+- **Existing guidelines?** {yes — description | no}
+- **Brand equity:** {what's working}
+- **Pain points:** {what's not working}
+
+### Evolution Scope (evolve only)
+- **Preserve:** {elements to keep}
+- **Evolve:** {elements to refresh}
+- **Replace:** {elements to redo}
+
+## Mission & Vision
+- **Mission:** {MISSION}
+- **Vision:** {VISION}
+- **Values:** {VALUES}
+
+## Audience
+- **Primary:** {PRIMARY_AUDIENCE}
+- **Secondary:** {SECONDARY_AUDIENCE}
+- **Demographics:** {DEMOGRAPHICS}
+- **Psychographics:** {PSYCHOGRAPHICS}
+
+## Personality
+- **Brand personality:** {PERSONALITY}
+- **Tone:** {TONE}
+- **How should the brand feel?** {FEELING}
+
+## Competitive Landscape
+- **Direct competitors:** {COMPETITORS}
+- **What sets you apart?** {DIFFERENTIATORS}
+- **Brands admired:** {BRANDS}
+
+## Inspiration
+- **Styles liked:** {STYLES}
+- **Styles to avoid:** {AVOID}
+- **Existing assets:** {ASSETS}
+
+## Constraints
+- **Timeline:** {TIMELINE}
+- **Budget:** {BUDGET}
+- **Must-haves:** {MUST_HAVES}
+- **Non-negotiables:** {NON_NEGOTIABLES}
+
+## Goals
+- **Business goal:** {BUSINESS_GOAL}
+- **Brand goal:** {BRAND_GOAL}
+- **Success metrics:** {METRICS}
+
+## Deliverables
+- [ ] Discovery & research
+- [ ] Brand strategy
+- [ ] Verbal identity
+- [ ] Visual identity
+- [ ] Color palettes
+
+## Notes
+{ADDITIONAL_NOTES}

package/templates/branding/config.json

@@ -0,0 +1,26 @@
+{
+  "version": "0.4.0",
+  "project_type": "brand",
+  "brand": {
+    "name": "",
+    "created": ""
+  },
+  "brand_mode": "new",
+  "evolution_scope": {
+    "preserve": [],
+    "evolve": [],
+    "replace": []
+  },
+  "phases": {
+    "audit": { "status": "skipped", "output": "audit/" },
+    "discover": { "status": "pending", "output": "discover/" },
+    "strategy": { "status": "pending", "output": "strategy/" },
+    "verbal": { "status": "pending", "output": "verbal/" },
+    "identity": { "status": "pending", "output": "identity/" },
+    "system": { "status": "pending", "output": "system/" }
+  },
+  "system_config": {
+    "tech_stack": "",
+    "system_strategy": "generate"
+  }
+}

package/templates/branding/roadmap.md

@@ -0,0 +1,43 @@
+# Brand Roadmap
+
+## Brand: {BRAND_NAME}
+**Created:** {DATE}
+
+---
+
+## Phase 0: Audit (optional)
+**Status:** skipped
+**Command:** `/gsp:brand-audit`
+**Input:** Existing brand assets + BRIEF.md
+**Output:** `audit/`
+**Goal:** Audit existing brand. Assess coherence, market fit, equity. Produce evolution map.
+**When:** Run when evolving an existing brand. Skip for new brands.
+
+## Phase 1: Research
+**Status:** pending
+**Command:** `/gsp:brand-research`
+**Input:** BRIEF.md
+**Output:** `discover/`
+**Goal:** Research market landscape, audience personas, competitive positioning, trends.
+
+## Phase 2: Strategy
+**Status:** pending
+**Command:** `/gsp:brand-strategy`
+**Input:** BRIEF.md + discover/
+**Output:** `strategy/`
+**Goal:** Define brand positioning — archetype, positioning map, personality, messaging.
+
+## Phases 3-4: Identity (Verbal + Visual)
+**Status:** pending
+**Command:** `/gsp:brand-identity`
+**Input:** BRIEF.md + strategy/
+**Output:** `verbal/` + `identity/` + `palettes.json`
+**Goal:** Build verbal and visual identity — voice, tone, logo, color, typography.
+**Granular re-run:** `/gsp:brand-verbal` (phase 3 only)
+
+## Phase 5: Patterns (Design System)
+**Status:** pending
+**Command:** `/gsp:brand-patterns`
+**Input:** Identity + Strategy + Verbal + BRIEF.md
+**Output:** `system/` (foundations, components, tokens.json) + `preview.html`
+**Goal:** Build design system, generate brand preview, transition to project diamond.

package/templates/branding/state.md

@@ -0,0 +1,29 @@
+# Brand State
+
+## Brand: {BRAND_NAME}
+**Started:** {DATE}
+**Mode:** {new | evolve}
+**Current Phase:** 0 (Not started)
+**Prettiness Level:** 0%
+
+---
+
+## Phase Progress
+
+| # | Phase | Status | Started | Completed |
+|---|-------|--------|---------|-----------|
+| 0 | Audit | skipped | — | — |
+| 1 | Discover | pending | — | — |
+| 2 | Strategy | pending | — | — |
+| 3 | Verbal | pending | — | — |
+| 4 | Identity | pending | — | — |
+| 5 | System | pending | — | — |
+
+## Status Values
+<!-- pending | in-progress | complete | needs-revision | skipped -->
+
+## Decisions
+<!-- Key brand decisions and rationale -->
+
+## Notes
+<!-- Session notes, observations, blockers -->

package/templates/changelog.md

@@ -0,0 +1,4 @@
+# Design Changelog
+> One entry per completed project. Scan this for quick codebase history.
+
+<!-- newest first -->

package/templates/codebase-inventory.md

@@ -0,0 +1,71 @@
+# Codebase Inventory
+
+> Auto-generated by `/gsp:new` during codebase analysis.
+> Downstream phases consume this instead of rescanning.
+
+## Classification
+
+**Codebase type:** `{greenfield | boilerplate | existing}`
+
+**Rationale:** {Why this classification — e.g., "Fresh create-next-app with no custom components", "Has 12 custom components and a theme system"}
+
+## Tech Stack
+
+| Layer | Value |
+|-------|-------|
+| Framework | {e.g., Next.js 14, Expo 51, Vite + React} |
+| Language | {e.g., TypeScript, JavaScript} |
+| Styling | {e.g., Tailwind CSS, CSS Modules, StyleSheet} |
+| UI Kit | {e.g., shadcn/ui, RN Reusables, none} |
+| Package Manager | {e.g., npm, pnpm, bun, yarn} |
+| Build Tool | {e.g., Next.js built-in, Vite, Metro} |
+
+## Existing Components
+
+| Component | Path | Props / Variants | Reusable? | Notes |
+|-----------|------|------------------|-----------|-------|
+| {name} | {path} | {key props} | {yes/no/partially} | {notes} |
+
+## Tokens & Theming
+
+**Token source:** {e.g., `tailwind.config.ts`, `globals.css`, `theme.ts`, `tokens.json`}
+**Format:** {e.g., CSS custom properties, Tailwind theme, JS object, JSON tokens}
+
+| Category | Defined? | Details |
+|----------|----------|---------|
+| Colors | {yes/no} | {e.g., "Custom palette in tailwind.config.ts extend.colors"} |
+| Typography | {yes/no} | {e.g., "Custom fonts via next/font, scale in Tailwind"} |
+| Spacing | {yes/no} | {e.g., "Default Tailwind spacing"} |
+| Radii | {yes/no} | {details} |
+| Shadows | {yes/no} | {details} |
+| Dark mode | {yes/no} | {e.g., "CSS class strategy via next-themes"} |
+
+## Architecture Patterns
+
+| Pattern | Value |
+|---------|-------|
+| Component style | {e.g., functional components, forwardRef wrappers, compound components} |
+| State management | {e.g., React Context, Zustand, Redux, useState only} |
+| Data fetching | {e.g., Server Components, React Query, SWR, fetch in useEffect} |
+| Routing | {e.g., Next.js App Router, Expo Router, React Router} |
+| File organization | {e.g., feature-based, type-based, flat} |
+
+## Conventions
+
+| Convention | Value |
+|------------|-------|
+| Naming | {e.g., PascalCase components, kebab-case files, camelCase utils} |
+| Exports | {e.g., named exports, default exports, barrel files} |
+| Styling approach | {e.g., `cn()` utility, `className` strings, `StyleSheet.create`} |
+| Import aliases | {e.g., `@/` → `src/`, `~/` → project root} |
+
+## Key Paths
+
+| Path | Purpose |
+|------|---------|
+| Components | {e.g., `src/components/`, `components/ui/`} |
+| Layouts | {e.g., `src/app/layout.tsx`, `app/(tabs)/_layout.tsx`} |
+| Pages / Screens | {e.g., `src/app/`, `app/(tabs)/`} |
+| Tokens / Theme | {e.g., `tailwind.config.ts`, `src/styles/globals.css`} |
+| Config | {e.g., `next.config.js`, `app.json`} |
+| Public / Assets | {e.g., `public/`, `assets/`} |

package/templates/exports-index.md

@@ -0,0 +1,93 @@
+# GSP Design Exports
+
+> Load this file first, then load only the chunks needed for your task.
+
+## Usage
+
+This file is the entry point for coding agents consuming GSP design output.
+
+1. Read this file to find chunk paths for your task
+2. Load only the chunks relevant to your current screen or component
+3. Each chunk is self-contained — follow `## Related` links for cross-references
+
+## Quick Reference
+
+- Building a screen? → Design table → load screen chunk + referenced components
+- Need a component spec? → Components table (in brand system)
+- Need color/type/spacing? → Foundations table (in brand system)
+- Need project scope? → Brief table
+- Need UX patterns or reference specs? → Research table
+
+## Design System (Brand-Level)
+
+<!-- BEGIN:system -->
+| Section | Chunk | Lines |
+|---------|-------|-------|
+| _(populated by /gsp:brand-system — lives in brand directory)_ | | |
+
+### Foundations
+
+| Foundation | File | Tokens |
+|------------|------|--------|
+| | | |
+
+### Components
+
+| Component | File | States | Variants |
+|-----------|------|--------|----------|
+| | | | |
+<!-- END:system -->
+
+## Project Brief
+
+<!-- BEGIN:brief -->
+| Section | File |
+|---------|------|
+| _(populated by /gsp:brief)_ | |
+<!-- END:brief -->
+
+## Project Research
+
+<!-- BEGIN:research -->
+| Section | File |
+|---------|------|
+| _(populated by /gsp:research)_ | |
+<!-- END:research -->
+
+## Design
+
+<!-- BEGIN:design -->
+| # | Screen | File | Components Used |
+|---|--------|------|-----------------|
+| _(populated by /gsp:design)_ | | | |
+
+### Shared
+
+| Section | File |
+|---------|------|
+| | |
+<!-- END:design -->
+
+## Design Critique
+
+<!-- BEGIN:critique -->
+| Section | File |
+|---------|------|
+| _(populated by /gsp:critique)_ | |
+<!-- END:critique -->
+
+## Deliverable Review
+
+<!-- BEGIN:review -->
+| Section | File |
+|---------|------|
+| _(populated by /gsp:review)_ | |
+<!-- END:review -->
+
+## Launch Campaign (Optional)
+
+<!-- BEGIN:launch -->
+| Section | File |
+|---------|------|
+| _(populated by /gsp:launch — optional)_ | |
+<!-- END:launch -->

package/templates/manifest.md

@@ -0,0 +1,19 @@
+# Build Manifest: {project-name}
+> Brand: {brand} | Built: {DATE} | Status: {complete|partial}
+> Branch: {branch or "—"} | PR: {pr-url or "—"}
+
+## Components
+
+| # | Component | Path | Action |
+|---|-----------|------|--------|
+{rows — one per component built. Action: added | modified}
+
+## Patterns
+
+| # | Pattern | Description |
+|---|---------|-------------|
+{rows — conventions established by this project, or "No new patterns."}
+
+## Files Touched
+
+{flat list of all target file paths, one per line with `- ` prefix}

package/templates/phases/brief.md

@@ -0,0 +1,53 @@
+# Project Brief
+
+## Project: {PROJECT_NAME}
+**Brand:** {BRAND_NAME}
+**Date:** {DATE}
+
+---
+
+> This phase scopes the project. Produces planning chunks + INDEX.md in the `brief/` directory.
+
+## Chunk Mapping
+
+### Brief Chunks (`brief/`)
+
+| Chunk File | Content |
+|-----------|---------|
+| `scope.md` | Screen/component list, priorities, project boundaries |
+| `target-adaptations.md` | Project-specific component adaptations from the brand system |
+| `install-manifest.md` | Install commands for needed components (conditional — shadcn/rn-reusables only) |
+| `gap-analysis.md` | Components/tokens in design but not in codebase (conditional — existing target only) |
+| `file-references.md` | Paths to existing components/tokens being used (conditional — existing target only) |
+
+## Content Reference
+
+Each chunk follows the format in `references/chunk-format.md`. Below is the structural reference for what each chunk should contain:
+
+### scope.md
+- **Screen list:** prioritized list of screens to design and build
+- **Component scope:** which brand system components this project uses
+- **Project boundaries:** what's in scope and out of scope
+- **Success criteria:** measurable outcomes for the project
+- **Dependencies:** external systems, APIs, content needs
+- **Issue framing:** how this project maps to bounded issues/PRs
+
+### target-adaptations.md
+- **Token overrides:** project-specific token adjustments (if any)
+- **Component adaptations:** brand components that need project-specific variants
+- **Platform considerations:** platform-specific adjustments (mobile, desktop, etc.)
+- **Implementation target mapping:** design components → target primitives (shadcn, rn-reusables, existing, code)
+- Links to brand system components: `{BRAND_PATH}/system/components/{name}.md`
+
+### install-manifest.md
+- Install commands for all needed components
+- Only produced for shadcn/rn-reusables targets
+
+### gap-analysis.md
+- Components in brand system but not in project codebase
+- Tokens in brand system but not in project codebase
+- Only produced for existing target codebases
+
+### file-references.md
+- Paths to all existing components/tokens being used
+- Only produced for existing target codebases