get-shit-pretty 0.6.3 → 0.7.0

package/gsp/skills/gsp-visuals/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gsp-visuals
+description: "Define visual direction — imagery, 3D, video, textures, and surface treatments"
+user-invocable: true
+model: sonnet
+allowed-tools:
+  - Read
+  - Write
+  - AskUserQuestion
+  - Glob
+  - Grep
+  - WebSearch
+---
+<context>
+Composable visual direction skill. Routes to domain expertise for imagery, 3D/WebGL, video/motion, or textures/surfaces.
+</context>
+
+<objective>
+Define visual direction for a specific domain. Reads the domain framework from `domains/` and follows it.
+
+**Input:** Domain flag (`--imagery`, `--3d`, `--video`, `--textures`) + optional `--enrich`
+**Output:** Domain-specific chunk file
+**Agent:** None — inline skill with structured questioning
+</objective>
+
+<execution_context>
+@${CLAUDE_SKILL_DIR}/chunk-format.md
+</execution_context>
+
+<rules>
+- Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
+- Route to exactly one domain per invocation
+</rules>
+
+<process>
+## Step 0: Parse flags
+
+Map invocation to domain file:
+| Flag | Domain file |
+|------|-------------|
+| `--imagery` | `imagery.md` |
+| `--3d` | `3d.md` |
+| `--video` | `video.md` |
+| `--textures` | `textures.md` |
+
+Check for `--enrich` flag (passes through to domain workflow).
+
+## Step 1: Pick domain (if no flag)
+
+If no domain flag was provided, use `AskUserQuestion`:
+- **Imagery** — "photography, illustration, iconography, image treatments"
+- **3D / WebGL** — "render style, materials, lighting, interactive scenes"
+- **Video / Motion** — "editing style, pacing, transitions, motion graphics"
+- **Textures / Surfaces** — "patterns, grain, gradients, background CSS recipes"
+
+## Step 2: Resolve brand/project context
+
+Check what's available:
+1. **Within a brand** — read `{BRAND_PATH}/BRIEF.md`, `{BRAND_PATH}/strategy/archetype.md`, `{BRAND_PATH}/identity/color-system.md` if they exist. Use brand personality to drive direction.
+2. **Within a project** — read `{PROJECT_PATH}/brand.ref` -> resolve brand -> load above.
+3. **Standalone** — no brand context. The domain's interactive mode will gather input.
+
+Resolve `{BRAND_PATH}` and `{PROJECT_PATH}` by checking for `.design/` in the workspace via Glob.
+
+## Step 3: Load domain and execute
+
+Read `${CLAUDE_SKILL_DIR}/domains/{domain}.md` and follow its complete framework:
+- If `--enrich`: follow the domain's enrich-mode workflow
+- Otherwise: follow the domain's interactive-mode questions, then its direction framework
+
+## Step 4: Write output and complete
+
+Resolve output path from domain file's **Output filename**:
+- Within a brand: `{BRAND_PATH}/identity/{filename}`
+- Within a project: `{PROJECT_PATH}/references/{filename}`
+- Standalone: display output, offer to save
+
+Write chunk following `chunk-format.md` format. Update STATE.md if it exists.
+
+Display the domain's completion summary, then show its completion options via `AskUserQuestion`.
+</process>

package/gsp/skills/gsp-visuals/chunk-format.md

@@ -0,0 +1,79 @@
+# Chunk Format Reference
+
+Standard format for all GSP phase output files. Chunks are the primary output — agents write chunks directly, not monoliths.
+
+## File Format
+
+Every chunk follows this structure:
+
+    # {Section/Component/Screen Name}
+
+    > Phase: {phase} | Brand/Project: {name} | Generated: {DATE}
+
+    ---
+
+    {Content for this chunk}
+
+    ---
+
+    ## Related
+
+    - [{Related chunk name}]({relative-path-to-related-chunk})
+
+## Naming Conventions
+
+- **Singular, kebab-case, lowercase:** "Buttons" → `button.md`, "Date Picker" → `date-picker.md`
+- **Screen files:** `screen-{NN}-{kebab-case-name}.md` (e.g., `screen-01-home.md`)
+
+## INDEX.md Format
+
+Each phase directory gets an INDEX.md manifest:
+
+    # {Phase Name}
+    > Phase: {phase} | Brand/Project: {name} | Generated: {DATE}
+
+    | Chunk | File | ~Lines |
+    |-------|------|--------|
+    | {Section} | [{filename}](./{filename}) | ~{N} |
+
+Lightweight — just a lookup table. No prose.
+
+## Rules
+
+- **Chunks are primary output** — agents write chunks directly to the phase directory
+- **No monoliths** — do not write a single large file then re-chunk it
+- **Size target:** 50-200 lines per chunk
+- **Self-contained:** each chunk must be understandable without loading other chunks
+- **Cross-references:** `## Related` section uses relative paths to related chunks
+- **Idempotent:** re-running a phase regenerates all chunks in that phase directory
+
+## Output Budgets
+
+Context is finite. Every line in a chunk is consumed by downstream agents. Budget accordingly.
+
+### Per-chunk budgets
+
+| Chunk type | Target | Hard max | Notes |
+|-----------|--------|----------|-------|
+| Phase chunk (design, research, etc.) | 50-150 lines | 200 lines | Self-contained, one concept per chunk |
+| INDEX.md | 10-30 lines | 50 lines | Lookup table only, no prose |
+| BUILD-LOG.md | 50-100 lines | 150 lines | Summary + tables, not narrative |
+| Component spec | 30-80 lines | 120 lines | Props, states, behavior — not full implementation |
+| Screen spec | 80-150 lines | 200 lines | Layout, components, interactions, states |
+
+### Per-phase budgets (total across all chunks)
+
+| Phase | Target total | Hard max | Typical chunks |
+|-------|-------------|----------|----------------|
+| Brief | 100-200 lines | 300 lines | 2-4 |
+| Research | 200-400 lines | 600 lines | 5-8 |
+| Design | 300-600 lines | 800 lines | 6-12 |
+| Critique | 100-200 lines | 300 lines | 2-4 |
+| Build log | 50-100 lines | 150 lines | 1 |
+| Review | 100-200 lines | 300 lines | 2-4 |
+
+### Terminal output (inline skills)
+
+- **Diagnostic** (doctor, progress): uncapped — user needs to see it, does not persist in agent context
+- **Greeting/status** (start): 20-40 lines
+- **Phase transitions**: 10-20 lines

package/gsp/skills/{gsp-3d/SKILL.md → gsp-visuals/domains/3d.md}

@@ -1,59 +1,24 @@
----
-name: gsp-3d
-description: Define 3D & WebGL direction — render style, materials, lighting, camera, interactive scenes
-user-invocable: true
-model: sonnet
-allowed-tools:
-  - Read
-  - Write
-  - AskUserQuestion
-  - Glob
-  - Grep
-  - WebSearch
----
-<context>
-You are a GSP 3D director. You define the brand's 3D and WebGL visual language — render aesthetic, material philosophy, lighting direction, camera behavior, and interactive scene design.
+# 3D Domain
 
-This is a standalone composable skill. It works two ways:
-1. **Standalone** — user runs `/gsp-3d` directly for 3D direction
-2. **As a building block** — invoked during identity or project phases when the brand needs 3D/WebGL content direction
+**Output filename:** `3d-direction.md`
 
-3D is no longer a niche — product configurators, immersive heroes, interactive showcases, and spatial UI are becoming standard. A consistent 3D language ensures renders and scenes feel like the same brand.
-</context>
+## Role
 
-<objective>
-Define 3D and WebGL visual direction for a brand or project.
+You are a GSP 3D director. You define the brand's 3D and WebGL visual language — render aesthetic, material philosophy, lighting direction, camera behavior, and interactive scene design.
 
-**Input:** Brand context or user description, OR `--enrich` mode
-**Output:** `3d-direction.md` chunk with render style, materials, lighting, camera, and interaction specs
-**Agent:** None — inline skill with structured questioning
-</objective>
+3D is no longer a niche — product configurators, immersive heroes, interactive showcases, and spatial UI are becoming standard. A consistent 3D language ensures renders and scenes feel like the same brand.
 
-<execution_context>
-@${CLAUDE_SKILL_DIR}/../../references/chunk-format.md
-</execution_context>
+## Rules
 
-<rules>
-- Always use `AskUserQuestion` for user interaction — never prompt via plain text
-- One decision per question — never batch multiple questions in a single message
 - 3D direction must align with brand's 2D aesthetic — if flat design, renders should be clean/minimal; if neubrutalism, renders can be bold/graphic
 - Specify concrete tools/libraries where applicable (Three.js, React Three Fiber, Spline, Blender)
 - Performance constraints matter — specify polygon budget, texture resolution, loading strategy
-</rules>
-
-<process>
-## Step 0: Determine mode
 
-| Input | Mode |
-|-------|------|
-| `/gsp-3d --enrich` | Enrich existing 3D direction |
-| `/gsp-3d` | Interactive — define 3D language |
-
-## Step 1: Enrich mode (`--enrich`)
+## Enrich mode (`--enrich`)
 
 Read existing brand context (`.yml` tokens, STYLE.md patterns/constraints). Derive 3D direction that's coherent with the 2D visual language.
 
-## Step 2: Interactive mode
+## Interactive mode
 
 One `AskUserQuestion` at a time:
 
@@ -71,7 +36,7 @@ One `AskUserQuestion` at a time:
    - **Abstract** — "generative, particle systems, noise-driven"
    - **Clay/soft** — "rounded, matte, toy-like (matches claymorphism)"
 
-## Step 3: Define 3D direction
+## Direction framework
 
 ### Render Style
 - **Aesthetic:** photorealistic / stylized / minimal / abstract
@@ -106,7 +71,57 @@ One `AskUserQuestion` at a time:
 - **Z-depth relationship:** 3D behind UI, 3D as UI element, mixed
 - **Transition:** how the user moves between 3D and 2D contexts
 
-## Step 4: Write output + completion
+## Output structure (target: 80-120 lines)
+
+```markdown
+# 3D Direction
+
+> Phase: identity | Brand: {name} | Generated: {DATE}
+
+---
+
+## Render Style
+{aesthetic, geometry, color}
+
+## Materials
+{primary, surface quality, brand material}
+
+## Lighting
+{setup, key light, ambient, shadows}
+
+## Camera
+{perspective, movement, framing}
+
+## Interaction
+{library, controls, performance, loading, fallback}
+
+## Integration with 2D
+{how 3D meets UI, z-depth, transitions}
+
+## Anti-Patterns
+{what to avoid}
+
+---
+
+## Related
+- [imagery-style.md](./imagery-style.md)
+- [STYLE.md](../patterns/STYLE.md)
+```
+
+## Completion display
+
+```
+  /gsp-visuals --3d — 3D direction defined
+
+    aesthetic      {style}
+    materials      {primary material}
+    lighting       {setup}
+    interaction    {library} — {controls}
+```
+
+## Completion options
 
-Write `3d-direction.md` chunk. Target: 80-120 lines.
-</process>
+Use `AskUserQuestion`:
+- **Continue to identity** — proceed with `/gsp-brand-identity`
+- **Refine** — adjust a specific area
+- **Done** — that's all

package/gsp/skills/{gsp-images/SKILL.md → gsp-visuals/domains/imagery.md}

@@ -1,56 +1,21 @@
----
-name: gsp-images
-description: Define imagery direction — photography, illustration, iconography, and image treatments
-user-invocable: true
-model: sonnet
-allowed-tools:
-  - Read
-  - Write
-  - AskUserQuestion
-  - Glob
-  - Grep
-  - WebSearch
----
-<context>
-You are a GSP imagery director. You define the visual language beyond color and type — photography style, illustration approach, iconography system, and image treatment recipes.
+# Imagery Domain
 
-This is a standalone composable skill. It works two ways:
-1. **Standalone** — user runs `/gsp-images` directly for imagery direction
-2. **As a building block** — the creative-director invokes this during the branding diamond to produce `imagery-style.md`
+**Output filename:** `imagery-style.md`
 
-Imagery is the third pillar of visual identity alongside color and typography. It defines what things LOOK like — not token values, but visual direction that guides photo selection, illustration commissioning, icon usage, and image processing in code.
-</context>
+## Role
 
-<objective>
-Define a complete imagery direction for a brand or project.
+You are a GSP imagery director. You define the visual language beyond color and type — photography style, illustration approach, iconography system, and image treatment recipes.
 
-**Input:** Brand context (strategy, archetype, color palette) or user description
-**Output:** `imagery-style.md` chunk with photography, illustration, iconography, and treatment specs
-**Agent:** None — inline skill with structured questioning
-</objective>
+Imagery is the third pillar of visual identity alongside color and typography. It defines what things LOOK like — not token values, but visual direction that guides photo selection, illustration commissioning, icon usage, and image processing in code.
 
-<execution_context>
-@${CLAUDE_SKILL_DIR}/../../references/chunk-format.md
-</execution_context>
+## Rules
 
-<rules>
-- Always use `AskUserQuestion` for user interaction — never prompt via plain text
-- One decision per question — never batch multiple questions in a single message
 - Every imagery decision must connect to brand personality — "We use X because the brand is Y"
 - Provide concrete, actionable direction — not "use good photos" but "candid, desaturated, warm tone, eye-level, natural light"
 - Include anti-patterns — what to avoid is as important as what to use
 - Icon recommendations must name specific libraries with import paths
-</rules>
-
-<process>
-## Step 0: Determine mode
 
-| Input | Mode |
-|-------|------|
-| `/gsp-images --enrich` | Enrich existing imagery-style.md |
-| `/gsp-images` | Interactive — define imagery direction |
-
-### Enrich mode (`--enrich`)
+## Enrich mode (`--enrich`)
 
 Read existing `{BRAND_PATH}/identity/imagery-style.md`. Enrich with:
 - Specific icon library recommendation (npm package + import path) based on brand personality
@@ -61,18 +26,9 @@ Read existing `{BRAND_PATH}/identity/imagery-style.md`. Enrich with:
 
 Overwrite `imagery-style.md` with enriched version. Preserve the creative direction.
 
-### Interactive/context mode
-
-Check what's available:
-1. **Within a brand** — read `{BRAND_PATH}/BRIEF.md`, `{BRAND_PATH}/strategy/archetype.md`, `{BRAND_PATH}/identity/color-system.md` if they exist. Use brand personality to drive imagery direction.
-2. **Within a project** — read `{PROJECT_PATH}/brand.ref` → resolve brand → load above.
-3. **Standalone** — no brand context. Ask the user directly.
-
-If brand context exists, skip to Step 2 (derive direction from strategy).
-
-## Step 1: Interactive mode (no brand context)
+## Interactive mode
 
-Gather imagery direction through questions. One `AskUserQuestion` at a time:
+One `AskUserQuestion` at a time:
 
 1. What's the product/brand? (open-ended — gather enough to infer personality)
 2. Imagery vibe — use `AskUserQuestion` with options:
@@ -89,9 +45,9 @@ Gather imagery direction through questions. One `AskUserQuestion` at a time:
    - **Monochrome** — "single tint, high contrast"
    - **No treatment** — "images used as-is"
 
-## Step 2: Derive imagery direction
+## Direction framework
 
-Whether from brand context or user input, define these four domains:
+Define these four domains:
 
 ### Photography
 - **Style:** (editorial, candid, studio, aerial, macro, etc.)
@@ -111,7 +67,7 @@ Whether from brand context or user input, define these four domains:
 ### Iconography
 - **Library:** recommend a specific icon library with reasoning:
   - `lucide-react` — clean, consistent, 1000+ icons, MIT license
-  - `@phosphor-icons/react` — 6 weights (thin→fill), 1500+ icons
+  - `@phosphor-icons/react` — 6 weights (thin->fill), 1500+ icons
   - `@radix-ui/react-icons` — 15x15 grid, minimal, Radix ecosystem
   - `@heroicons/react` — Tailwind ecosystem, 20/24px, outline/solid
   - Custom SVG — when brand needs unique iconography
@@ -136,16 +92,8 @@ Whether from brand context or user input, define these four domains:
 - **Responsive:** art direction breakpoints, object-fit strategy
 - **Loading:** blur-up placeholder, skeleton, dominant color
 
-## Step 3: Write imagery-style.md
+## Output structure (target: 100-150 lines)
 
-Resolve output path:
-- Within a brand: `{BRAND_PATH}/identity/imagery-style.md`
-- Within a project: `{PROJECT_PATH}/references/imagery-style.md`
-- Standalone: display output, offer to save
-
-Write following `references/chunk-format.md` format. Target: 100-150 lines.
-
-Structure:
 ```markdown
 # Imagery Style
 
@@ -178,11 +126,10 @@ Structure:
 - [STYLE.md](../patterns/STYLE.md)
 ```
 
-## Step 4: Completion
+## Completion display
 
-Display summary:
 ```
-  /gsp-images — imagery direction defined
+  /gsp-visuals --imagery — imagery direction defined
 
     photography    {style} — {treatment}
     illustration   {style} — {when used}
@@ -190,8 +137,9 @@ Display summary:
     treatments     {key technique}
 ```
 
+## Completion options
+
 Use `AskUserQuestion`:
 - **Continue to identity** — proceed with `/gsp-brand-identity`
 - **Refine** — adjust a specific domain
 - **Done** — that's all
-</process>

package/gsp/skills/{gsp-textures/SKILL.md → gsp-visuals/domains/textures.md}

@@ -1,55 +1,21 @@
----
-name: gsp-textures
-description: Design surface treatments — patterns, grain, gradients, background CSS recipes
-user-invocable: true
-model: sonnet
-allowed-tools:
-  - Read
-  - Write
-  - AskUserQuestion
-  - Glob
-  - Grep
----
-<context>
-You are a GSP texture director. You design surface treatments — noise grain, halftone patterns, grid overlays, gradient meshes, and background CSS recipes that give flat interfaces tactile depth.
+# Textures Domain
 
-This is a standalone composable skill. It works two ways:
-1. **Standalone** — user runs `/gsp-textures` directly for surface treatment exploration
-2. **As a building block** — the creative-director invokes `/gsp-textures --enrich` to add CSS texture recipes to creative direction
+**Output filename:** `textures.md`
 
-Textures are what separate a generic flat UI from a design with presence. A subtle noise grain at 3% opacity transforms a blank canvas into warm paper. A halftone dot pattern turns a section break into a visual signature. These are the details that make a design feel crafted.
-</context>
+## Role
 
-<objective>
-Define surface treatments and produce copy-paste CSS recipes.
+You are a GSP texture director. You design surface treatments — noise grain, halftone patterns, grid overlays, gradient meshes, and background CSS recipes that give flat interfaces tactile depth.
 
-**Input:** Brand context (style constraints, surface philosophy) or user direction, OR `--enrich` mode
-**Output:** `textures.md` chunk with CSS recipes for each surface treatment
-**Agent:** None — inline skill with CSS generation
-</objective>
+Textures are what separate a generic flat UI from a design with presence. A subtle noise grain at 3% opacity transforms a blank canvas into warm paper. A halftone dot pattern turns a section break into a visual signature. These are the details that make a design feel crafted.
 
-<execution_context>
-@${CLAUDE_SKILL_DIR}/../../references/chunk-format.md
-</execution_context>
+## Rules
 
-<rules>
-- Always use `AskUserQuestion` for user interaction — never prompt via plain text
-- One decision per question — never batch multiple questions in a single message
 - Every texture must include copy-paste CSS (not just descriptions)
 - Textures must be applied via fixed pseudo-elements (pointer-events: none) — never on scrolling containers
 - Always specify opacity + blend mode — textures at wrong opacity ruin the design
 - Respect style constraints — if the brand `.yml` says "never: texture" then the answer is "clean surfaces"
-</rules>
-
-<process>
-## Step 0: Determine mode
 
-| Input | Mode |
-|-------|------|
-| `/gsp-textures --enrich` | Enrich existing imagery-style.md textures section |
-| `/gsp-textures` | Interactive — explore and build |
-
-## Step 1: Enrich mode (`--enrich`)
+## Enrich mode (`--enrich`)
 
 Read existing `{BRAND_PATH}/identity/imagery-style.md` and `{BRAND_PATH}/patterns/{brand}.yml`.
 
@@ -59,7 +25,7 @@ Otherwise, derive textures from the style's `layout.surfaces` field and the `.md
 
 Update the Textures & Patterns section of `imagery-style.md`.
 
-## Step 2: Interactive mode
+## Interactive mode
 
 One `AskUserQuestion` at a time:
 
@@ -76,9 +42,9 @@ One `AskUserQuestion` at a time:
    - **Cards only** — "texture inside card surfaces"
    - **Decorative** — "only on decorative elements"
 
-## Step 3: Generate CSS recipes
+## CSS recipe library
 
-For each texture, produce:
+For each texture, produce production-ready CSS:
 
 ### Noise grain
 ```css
@@ -124,9 +90,49 @@ For each texture, produce:
 }
 ```
 
-Customize values to match brand palette and style constraints.
+Customize all values to match brand palette and style constraints.
+
+## Output structure (target: 60-100 lines)
+
+```markdown
+# Textures
+
+> Phase: identity | Brand: {name} | Generated: {DATE}
+
+---
+
+## Surface Philosophy
+{why these textures, how they express the brand}
+
+## Texture Recipes
+{each texture with full CSS, opacity, blend mode, placement}
+
+## Placement Rules
+{where textures go, where they don't}
+
+## Anti-Patterns
+{what to avoid}
+
+---
+
+## Related
+- [imagery-style.md](./imagery-style.md)
+- [STYLE.md](../patterns/STYLE.md)
+```
+
+## Completion display
+
+```
+  /gsp-visuals --textures — surface treatments defined
+
+    surfaces       {count} textures
+    technique      {primary technique}
+    placement      {strategy}
+```
 
-## Step 4: Write output + completion
+## Completion options
 
-Write `textures.md` chunk or update Textures section of `imagery-style.md`. Target: 60-100 lines.
-</process>
+Use `AskUserQuestion`:
+- **Continue to identity** — proceed with `/gsp-brand-identity`
+- **Refine** — adjust a texture
+- **Done** — that's all