get-shit-pretty 0.5.2 → 0.6.0

package/gsp/skills/gsp-brand-refine/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: brand-refine
+description: Targeted brand adjustments mid-project — tweak colors, typography, or spacing without re-running the full branding diamond
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Bash
+  - AskUserQuestion
+  - WebFetch
+---
+<context>
+You are a GSP brand refinement skill. You take targeted feedback about brand visual issues and surgically update token values — no need to re-run strategy or identity.
+
+This skill modifies **tokens.json** and **palettes.json** only. If the user's feedback is strategic ("make the tone more playful") or narrative ("the brand story feels off"), redirect to `/gsp:brand-strategy` or `/gsp:brand-identity`.
+</context>
+
+<objective>
+Accept natural language feedback about brand visuals, identify which tokens are affected, apply targeted value changes, and log what changed.
+
+**Input:** Natural language feedback (e.g., "accent is too muted", "heading weight too heavy")
+**Output:** Updated `tokens.json` and/or `palettes.json` + `REFINE-LOG.md`
+**Agent:** None — inline skill, surgical edits
+</objective>
+
+<execution_context>
+@${CLAUDE_SKILL_DIR}/../../references/design-tokens.md
+</execution_context>
+
+<rules>
+- Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- Never update artifacts without showing before/after and getting confirmation
+- Only touch tokens directly affected by the feedback
+- Preserve existing token structure — edit values in place, don't restructure
+- When changing a color that cascades into semantic tokens, show the full cascade before applying
+- When color changes affect text/background pairs, check WCAG AA contrast (4.5:1 normal text, 3:1 large text) and warn if a change would fail
+</rules>
+
+<process>
+## Step 0: Locate brand and parse feedback
+
+Extract feedback from the user's input (everything after `/gsp:brand-refine`).
+
+If no feedback provided, use `AskUserQuestion`: "What would you like to adjust? (e.g., 'accent is too muted', 'heading font feels too heavy', 'spacing too tight')"
+
+Resolve brand from `.design/branding/` (one → use it, multiple → ask). Set `BRAND_PATH`.
+Check that `{BRAND_PATH}/patterns/tokens.json` exists. If not: "No tokens found. Run `/gsp:brand-patterns` first."
+
+## Step 1: Read current state
+
+Read `{BRAND_PATH}/patterns/tokens.json` once. Extract all sections relevant to the feedback:
+
+| Feedback signals | Token section |
+|-----------------|---------------|
+| color, accent, muted, vibrant, contrast, tint, shade, hue | `color` |
+| font, heading, body, weight, size, line-height | `typography` |
+| spacing, padding, gap, tight, loose, dense | `spacing` |
+| shadow, elevation, depth, flat | `shadow` |
+| radius, rounded, sharp, corners | `borderRadius` |
+
+Also read `{BRAND_PATH}/identity/palettes.json` if it exists and feedback involves colors.
+
+## Step 2: Propose changes
+
+Show a clear before/after for each affected token:
+
+```
+  /gsp:brand-refine
+  ═══════════════════════════════════════
+
+  Feedback: "the accent is too muted"
+
+  ─── Proposed Changes ─────────────────
+
+  color.brand.accent
+    before: #B8860B
+    after:  #E8A317
+    change: increased chroma
+
+  Cascade:
+    color.semantic.link        → #E8A317
+    color.semantic.focus-ring  → #E8A317
+
+  Contrast: accent on white 3.2:1 → 2.8:1 ⚠️ below AA
+            accent on dark  8.4:1 → 9.2:1 ✓
+
+  ─────────────────────────────────────
+```
+
+### Color changes involving palette scales
+
+If the change affects a source color that feeds an 11-stop palette, use `AskUserQuestion`:
+- **Regenerate scale** — regenerate the full 11-stop OKLCH palette from the new color
+- **Just update tokens** — only change the specific token values
+
+If regenerating, call the tints.dev API:
+```
+WebFetch: https://www.tints.dev/api/{colorName}/{hexWithoutHash}
+```
+Parse the response for the 11-stop OKLCH scale (50–950) and update `palettes.json`.
+
+### Typography changes involving scale ratio
+
+For individual token tweaks (weight, letter-spacing), propose direct value changes. If the user wants a different ratio or base size that would affect the entire scale, recalculate using the existing scale's mathematical relationship.
+
+## Step 3: Confirm and apply
+
+Use `AskUserQuestion`:
+- **Apply all** — "apply all proposed changes"
+- **Adjust first** — "I want to tweak some values"
+- **Cancel** — "keep current values"
+
+Apply confirmed changes:
+1. **tokens.json** — edit values in place with `Edit`. Preserve structure.
+2. **palettes.json** — update if palette was regenerated.
+
+## Step 4: Log and finish
+
+Append to `{BRAND_PATH}/REFINE-LOG.md`:
+
+```markdown
+## {DATE} — "{feedback}"
+
+| Token | Before | After |
+|-------|--------|-------|
+| color.brand.accent | #B8860B | #E8A317 |
+| color.semantic.link | #B8860B | #E8A317 |
+```
+
+Display summary:
+
+```
+  /gsp:brand-refine — {n} tokens updated
+  ═══════════════════════════════════════
+
+  Updated: {list of tokens}
+  Log: {BRAND_PATH}/REFINE-LOG.md
+
+  ─────────────────────────────────────
+```
+
+Use `AskUserQuestion`:
+- **More refinements** — loop back to Step 0
+- **Done** — "that's all"
+</process>

package/gsp/skills/gsp-brand-research/SKILL.md

@@ -38,9 +38,7 @@ Research market context that will inform brand strategy.
 <process>
 ## Step 1: Resolve brand
 
-Scan `.design/branding/` for brand directories. One brand → use it. Multiple → use `AskUserQuestion` with one option per brand.
-
-Set `BRAND_PATH` = `.design/branding/{brand}`
+Resolve brand from `.design/branding/` (one → use it, multiple → ask). Set `BRAND_PATH`.
 
 Read `{BRAND_PATH}/BRIEF.md`. If missing, tell user to run `/gsp:start` first.
 Read `{BRAND_PATH}/config.json` for `brand_mode`.

package/gsp/skills/gsp-brand-strategy/SKILL.md

@@ -40,9 +40,7 @@ Define brand strategy and voice through interactive creative direction, then pro
 <process>
 ## Step 0: Resolve brand
 
-Scan `.design/branding/` for brand directories. One brand → use it. Multiple → use `AskUserQuestion`.
-
-Set `BRAND_PATH` = `.design/branding/{brand}`
+Resolve brand from `.design/branding/` (one → use it, multiple → ask). Set `BRAND_PATH`.
 If missing, tell user to run `/gsp:start` first.
 
 ## Step 1: Load context

package/gsp/skills/gsp-brand-sync/SKILL.md

@@ -45,10 +45,7 @@ Compare a project's shipped state against its source brand across all dimensions
 <process>
 ## Step 0: Resolve brand and project
 
-Scan `.design/branding/` for brand directories. One brand → use it. Multiple → use `AskUserQuestion`.
-
-Set `BRAND_PATH` = `.design/branding/{brand}`
-
+Resolve brand from `.design/branding/` (one → use it, multiple → ask). Set `BRAND_PATH`.
 Check that the brand has at least one of: `patterns/tokens.json`, `strategy/`, `identity/`. If none exist, tell the user: "No brand system found. Run `/gsp:brand-patterns` first."
 
 Verify the project codebase has shipped output — source files with components, copy, or styles.
@@ -74,6 +71,7 @@ Read `{BRAND_PATH}/sync/SYNC-REPORT.md`. Present a compact summary per dimension
 - **Tokens only** — just sync the quantitative token changes
 - **Pick by dimension** — choose which dimensions to sync
 - **Review each** — walk through every divergence individually
+- **Refine manually** — run `/gsp:brand-refine` to make targeted token adjustments instead
 - **Skip** — don't update the brand
 
 If "Pick by dimension", ask per dimension. If "Review each", walk through the Update Map from the report.

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

@@ -72,7 +72,7 @@ If all 4 phases complete, check:
 
 **Check B4: Legacy Monolith Detection**
 For each brand phase directory (discover, strategy, identity, patterns):
-- If monolith exists but no INDEX.md → WARN: "Legacy format in {phase}/ — re-run /gsp:brand-{phase} for chunk output"
+- If monolith exists but no INDEX.md → WARN: "Monolith files are no longer supported in GSP v0.6.0+. Re-run `/gsp:brand-{phase}` to generate chunk output."
 
 ### Per-Project Checks (6-phase)
 

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

@@ -42,6 +42,7 @@ Skill names are left-padded with 4 spaces. Descriptions start at column 27 (4 in
     /gsp:brand-identity    create visual identity
     /gsp:brand-patterns    build design system tokens and components
     /gsp:brand-sync        sync brand to match a project's shipped state
+    /gsp:brand-refine      tweak brand tokens mid-project without re-running identity
     /gsp:brand-audit       audit existing brand before evolving (optional)
 
   ─── Project ──────────────────────────

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

@@ -31,12 +31,9 @@ Create marketing campaign assets for product launch.
 <process>
 ## Step 0: Resolve project and brand
 
-Scan `.design/projects/` for project directories. If only one project exists, use it. If multiple, ask the user which project to work on.
+Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
-Set `PROJECT_PATH` = `.design/projects/{project}`
-
-Read `{PROJECT_PATH}/brand.ref` to resolve brand path:
-- Set `BRAND_PATH` = `.design/branding/{brand}`
+Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`.
 
 ## Step 1: Load context
 
@@ -49,9 +46,8 @@ Read `{PROJECT_PATH}/config.json` to get `design_scope`.
 ### Identity (selective, chunk-first)
 
 Read `{BRAND_PATH}/identity/INDEX.md`. If it exists, load all identity chunks.
-Fallback: read `{BRAND_PATH}/identity/IDENTITY.md`. Log: "⚠️ Legacy identity format detected."
 
-If neither exists, tell the user to complete the brand identity first.
+If it doesn't exist, tell the user to complete the brand identity first.
 
 ### Voice and Messaging (from strategy)
 
@@ -60,7 +56,6 @@ Read `{BRAND_PATH}/strategy/voice-and-tone.md` and `{BRAND_PATH}/strategy/messag
 ### Design (chunk-first)
 
 Read `{PROJECT_PATH}/design/INDEX.md`. If it exists, load all screen chunks.
-Fallback: read `{PROJECT_PATH}/screens/INDEX.md` (legacy path).
 
 ### Other
 

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

@@ -138,6 +138,8 @@ If a brand context exists (`.design/branding/{brand}/`):
 
 ## Step 5: Write palettes.json
 
+If `{OUTPUT_PATH}/palettes.json` already exists, use `AskUserQuestion`: "palettes.json already exists — overwrite with new palette?" with options **Overwrite** and **Cancel**. If cancelled, skip writing palettes.json and proceed to the next step.
+
 Write `{OUTPUT_PATH}/palettes.json` with the full OKLCH scales:
 
 ```json

package/gsp/skills/gsp-project-brief/SKILL.md

@@ -34,15 +34,9 @@ Scope the project and plan adaptations from the brand system.
 <process>
 ## Step 0: Resolve project and brand
 
-Scan `.design/projects/` for project directories. If only one project exists, use it. If multiple, ask the user which project to work on.
+Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
-Set `PROJECT_PATH` = `.design/projects/{project}`
-
-Read `{PROJECT_PATH}/brand.ref` to resolve brand path:
-- Extract `brand` name and `path` from brand.ref
-- Set `BRAND_PATH` = `.design/branding/{brand}`
-
-If brand.ref doesn't exist, tell the user to run `/gsp:start` to set up the project with a brand reference.
+Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`. If brand.ref doesn't exist, tell the user to run `/gsp:start`.
 
 ## Step 1: Load context
 
@@ -50,9 +44,7 @@ If brand.ref doesn't exist, tell the user to run `/gsp:start` to set up the proj
 
 Read `{BRAND_PATH}/patterns/INDEX.md`. If it exists, load all foundation chunks + selective component chunks.
 
-Fallback: read `{BRAND_PATH}/patterns/SYSTEM.md` (legacy monolith). Log: "⚠️ Legacy format detected."
-
-If neither exists, tell the user to run `/gsp:brand-patterns` first to create the brand's design patterns.
+If it doesn't exist, tell the user to run `/gsp:brand-patterns` first to create the brand's design patterns.
 
 Also read `{BRAND_PATH}/patterns/tokens.json`.
 

package/gsp/skills/gsp-project-build/SKILL.md

@@ -57,12 +57,9 @@ Implement designs as production-ready code in the codebase via phased pipeline w
 <process>
 ## Step 0: Resolve project and brand
 
-Scan `.design/projects/` for project directories. If only one project exists, use it. If multiple, ask the user which project to work on.
+Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
-Set `PROJECT_PATH` = `.design/projects/{project}`
-
-Read `{PROJECT_PATH}/brand.ref` to resolve brand path:
-- Set `BRAND_PATH` = `.design/branding/{brand}`
+Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`.
 
 ## Step 0.5: Validate prerequisites
 

package/gsp/skills/gsp-project-critique/SKILL.md

@@ -36,12 +36,9 @@ Critique design quality and audit accessibility compliance.
 <process>
 ## Step 0: Resolve project and brand
 
-Scan `.design/projects/` for project directories. If only one project exists, use it. If multiple, ask the user which project to work on.
+Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
-Set `PROJECT_PATH` = `.design/projects/{project}`
-
-Read `{PROJECT_PATH}/brand.ref` to resolve brand path:
-- Set `BRAND_PATH` = `.design/branding/{brand}`
+Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`.
 
 ## Step 1: Load context
 
@@ -52,13 +49,10 @@ Read `{PROJECT_PATH}/config.json` to get `implementation_target`, `design_scope`
 **BRIEF:** `{PROJECT_PATH}/BRIEF.md`
 
 **Identity:** Read `{BRAND_PATH}/identity/INDEX.md` → load all chunks.
-Fallback: `{BRAND_PATH}/identity/IDENTITY.md`.
 
 **Patterns:** Read `{BRAND_PATH}/patterns/INDEX.md` → load all chunks.
-Fallback: `{BRAND_PATH}/patterns/SYSTEM.md`.
 
 **Design:** Read `{PROJECT_PATH}/design/INDEX.md` → load all chunks.
-Fallback: `{PROJECT_PATH}/design/SCREENS.md` or `{PROJECT_PATH}/screens/INDEX.md` (legacy).
 
 **Brief:** Read `{PROJECT_PATH}/brief/INDEX.md` → load all chunks (if exists).
 
@@ -150,5 +144,7 @@ If verdict is **Fail**:
 ## Step 6: Phase transition output
 
 Render phase transition (see `references/phase-transitions.md`). This phase has pass/fail variants — the reference covers both.
+
+If critique identified brand-level issues (palette contrast, typography weight, spacing scale), note: "Some issues are brand-level — run `/gsp:brand-refine` to adjust tokens without re-running identity."
 </process>
 </output>

package/gsp/skills/gsp-project-design/SKILL.md

@@ -36,12 +36,9 @@ Design core UI/UX screens and interaction flows.
 <process>
 ## Step 0: Resolve project and brand
 
-Scan `.design/projects/` for project directories. If only one project exists, use it. If multiple, ask the user which project to work on.
+Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
-Set `PROJECT_PATH` = `.design/projects/{project}`
-
-Read `{PROJECT_PATH}/brand.ref` to resolve brand path:
-- Set `BRAND_PATH` = `.design/branding/{brand}`
+Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`.
 
 ## Step 0.5: Validate prerequisites
 
@@ -71,14 +68,11 @@ If `{PROJECT_PATH}/references/` exists, scan for files (images, PDFs, markdown,
 
 Read `{BRAND_PATH}/patterns/INDEX.md`. If it exists, load all foundation chunks + selective component chunks.
 
-Fallback: read `{BRAND_PATH}/patterns/SYSTEM.md` (legacy monolith). Log: "⚠️ Legacy format detected — consider re-running /gsp:brand-patterns for chunk output."
-
-If neither exists, tell the user to run `/gsp:brand-patterns` first.
+If it doesn't exist, tell the user to run `/gsp:brand-patterns` first.
 
 ### Brand context (selective)
 
 Read `{BRAND_PATH}/identity/INDEX.md`. If it exists, load `color-system.md`, `typography.md`, and `imagery-style.md`.
-Fallback: read `{BRAND_PATH}/identity/IDENTITY.md`.
 
 ### Brand style prompt (visual DNA)
 

package/gsp/skills/gsp-project-research/SKILL.md

@@ -36,12 +36,9 @@ Deep research into UX patterns, competitor experiences, and technical approaches
 <process>
 ## Step 0: Resolve project and brand
 
-Scan `.design/projects/` for project directories. If only one project exists, use it. If multiple, ask the user which project to work on.
+Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
-Set `PROJECT_PATH` = `.design/projects/{project}`
-
-Read `{PROJECT_PATH}/brand.ref` to resolve brand path:
-- Set `BRAND_PATH` = `.design/branding/{brand}`
+Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`.
 
 ## Step 1: Load context
 

package/gsp/skills/gsp-project-review/SKILL.md

@@ -32,12 +32,9 @@ QA validate the codebase implementation against design intent.
 <process>
 ## Step 0: Resolve project and brand
 
-Scan `.design/projects/` for project directories. If only one project exists, use it. If multiple, ask the user which project to work on.
+Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
-Set `PROJECT_PATH` = `.design/projects/{project}`
-
-Read `{PROJECT_PATH}/brand.ref` to resolve brand path:
-- Set `BRAND_PATH` = `.design/branding/{brand}`
+Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`.
 
 ## Step 1: Load context
 
@@ -54,7 +51,6 @@ Read `{PROJECT_PATH}/config.json` to get `implementation_target`, `design_scope`
 **Git diff:** Run `git diff` (and `git diff --cached`) to see what actually changed in the codebase. Cross-reference against BUILD-LOG.md.
 
 **Design:** Read `{PROJECT_PATH}/design/INDEX.md` → load all screen chunks.
-Fallback: `{PROJECT_PATH}/screens/INDEX.md` (legacy).
 
 **Brand patterns:** Read `{BRAND_PATH}/patterns/INDEX.md` → load foundation + component chunks.
 Also read `{BRAND_PATH}/patterns/tokens.json`.
@@ -175,4 +171,6 @@ If verdict is **Fail**:
 ## Step 6: Phase transition output
 
 Render phase transition (see `references/phase-transitions.md`). This phase has pass/fail variants — the reference covers both.
+
+If review identified brand-level issues (token values that don't work in context), note: "Some issues are brand-level — run `/gsp:brand-refine` to adjust tokens without re-running identity."
 </process>

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

@@ -71,12 +71,7 @@ Scan `.design/` for existing brands and projects:
 
 ### Step 1b: Run design system scan (background)
 
-Spawn a background agent with `run_in_background: true` that follows the `/gsp:design-system` skill methodology:
-- Use `subagent_type: "general-purpose"`
-- Prompt: "Follow the /gsp:design-system skill methodology. Scan the codebase and produce `.design/system/{STACK,COMPONENTS,TOKENS,CONVENTIONS,CONCERNS}.md`. Read the templates from the GSP templates/system/ directory for output format. If no package.json exists, write minimal greenfield versions."
-- Store the task reference — you'll read results in Step 3 Round 2 or Step 4.
-
-This produces workspace-level documents consumed by downstream skills and agents.
+Spawn `/gsp:design-system` as a background agent (`run_in_background: true`, `subagent_type: "general-purpose"`). It writes to `.design/system/` — don't wait for it. Store the task reference for Step 3 Round 2 or Step 4.
 
 ### Step 1c: Greet
 
@@ -92,39 +87,15 @@ Adapt the greeting based on what the scan revealed. Use plain text with Unicode
 - **Summary box:** `┌──┐│└──┘` border with key-value pairs inside
 
 **Fresh start (no `.design/`):**
-```
-  /gsp: ◇◇
-
-  looks like a fresh start.
-```
-
-If `package.json` exists, append:
-```
-  i scanning your codebase in the background — i'll factor in what i find.
-```
-
-Then use `AskUserQuestion` with options:
-- **Brand identity** — "define who you are — strategy, voice, visuals"
-- **Design project** — "design screens and flows for something you're building"
-- **Both (brand + project)** — "full pipeline — brand first, then design"
-- **Quick project** — "skip branding — pick a style preset and start designing"
+Show `  /gsp: ◇◇\n  looks like a fresh start.` (append codebase scanning note if `package.json` exists). Use `AskUserQuestion` with: Brand identity, Design project, Both (brand + project), Quick project.
 
 **Legacy `.design/` detected (flat structure, pre-0.4.0):**
-Acknowledge the legacy project, note it still works with current commands. Use `AskUserQuestion`:
-- **Start fresh brand** — "new dual-diamond brand alongside your legacy project"
-- **Start design project** — "new project using the updated pipeline"
-- **Keep working** — "continue with the legacy structure"
+Acknowledge the legacy project. Use `AskUserQuestion`: Start fresh brand, Start design project, Keep working.
 
 **Brands exist, no projects:**
-Show brand name + pipeline flow. Then use `AskUserQuestion` with:
-- One option per existing brand — "start a project with {brand name}"
-- **Create new brand** — "start a new brand identity"
+Show brand name + pipeline flow (compact single-line if complete, full pipeline if incomplete). Use `AskUserQuestion`: one option per existing brand + Create new brand.
 
-When brand is complete, show compact single-line: `  acme-corp                                          ◆ complete`
-
-When brand is incomplete, show full pipeline flow + `→ next: /gsp:{next-command}`
-
-**Brands + projects exist:**
+**Brands + projects exist (canonical format):**
 Show compact brand (single-line if complete) + full project pipeline flow. Then `AskUserQuestion`:
 - **Continue {project}** — "pick up at {next phase}"
 - **New project** — "start a new design project"
@@ -144,7 +115,7 @@ When codebase has been scanned (`.design/system/STACK.md` exists), show a Summar
 ```
 
 **Codebase signals found (any state):**
-Weave in what you found: "I see you've got a [Next.js/React Native/etc.] project here with [Tailwind/shadcn/etc.] — I'll factor that into the design scope."
+Weave in what you found naturally: framework, styling, component count.
 
 ## Step 2: Route based on conversation
 
@@ -169,22 +140,15 @@ mkdir -p .design/branding/{name}/{audit,discover,strategy,identity,patterns}
 
 **Round 1 — Business & People:**
 - Company name, industry, stage
-- What problem does this business solve? For whom? How differently?
-- Business model (how it makes money)
-- Who are the main competitors? (users usually know their top 2-3)
-- Primary persona — use `AskUserQuestion` to confirm or build: present an inferred persona profile (name, role, day-in-the-life, frustration, aspiration, discovery, trust signals) and let user correct. If they say "fintech for Gen Z" → infer and present a concrete persona.
+- Problem / audience / differentiation
+- Business model, main competitors (2-3)
+- Primary persona — infer a concrete profile (name, role, frustration, aspiration) from context and present for correction. Personas should feel like real people — dig into the emotional layer.
 - Secondary persona (if relevant)
 - Mission and vision
 
-This round is the most important. The personas should feel like real people, not demographic buckets. Dig into the emotional layer: anxiety, ambition, frustration, curiosity, status, safety.
-
 **Round 2 — Brand Essence & Landscape:**
 
-Before presenting personality options, **internally synthesize** from Round 1:
-- **Promise:** what should someone feel when they interact with this brand? (derived from persona frustrations + aspirations)
-- **Point of view:** what does this brand disagree with in the category? (derived from the problem + how it solves it differently)
-
-You do NOT ask the user these directly — you use them to ground the personality options.
+Before presenting personality options, **internally synthesize** promise (what should someone feel?) and point of view (what does this brand disagree with?) from Round 1. Don't ask these directly — use them to ground personality options.
 
 - Brand personality — use `AskUserQuestion` with 2-3 concrete personality directions. **Each option must explain WHY it fits this brand's audience and problem** — not just a style label:
   - Each option: **Label** (3 adjectives) / **Description** (why this personality fits their specific audience and competitive position — reference the persona by name, the problem, or the gap) / **Preview** (example sentence in that voice, using their product context)
@@ -218,39 +182,18 @@ Skip or compress rounds if the user gives enough upfront. Don't over-ask.
 
 5. Set `brand_mode` in config.json based on Step 2 routing decision.
 
-6. Route using `AskUserQuestion`:
-
-- **Brand-only, new →** Use `AskUserQuestion`: "Brand brief created! Want to keep going?"
-  - **Continue to research** — "Start brand research now" → invoke `/gsp:brand-research` via Skill tool
-  - **Stop here** — "I'll come back later" → confirm files are saved, show how to resume with `/gsp:start`
-  - **What happens next?** — "Explain the next phase" → explain what brand research does and how it uses the brief
-
-- **Brand-only, evolve →** Use `AskUserQuestion`: "Brand brief created! Let's audit your current brand."
-  - **Continue to audit** — "Audit my existing brand now" → invoke `/gsp:brand-audit` via Skill tool
-  - **Stop here** — "I'll come back later" → confirm files are saved, show how to resume with `/gsp:start`
-  - **What happens next?** — "Explain the audit phase" → explain what the brand audit does and why it comes before strategy
-
-- **E2E, new →** "Brand brief created. Now let's scope the design project." → continue to Step 4.
+6. Route using `AskUserQuestion` — always offer Continue / Stop here / What happens next:
 
-- **E2E, evolve →** Use `AskUserQuestion`: "Brand brief created! Let's audit your existing brand before the design project."
-  - **Continue to audit** — "Audit my existing brand now" → invoke `/gsp:brand-audit` via Skill tool
-  - **Stop here** — "I'll come back later" → confirm files are saved, show how to resume with `/gsp:start`
-  - **What happens next?** — "Explain the audit phase" → explain what the brand audit does and how it feeds into the rest of the pipeline
+- **Brand-only, new →** continue to `/gsp:brand-research`
+- **Brand-only, evolve →** continue to `/gsp:brand-audit`
+- **E2E, new →** auto-continue to Step 4
+- **E2E, evolve →** continue to `/gsp:brand-audit` (then Step 4 after audit)
 
 ## Step 4: Project flow
 
 **Background:** Run `git branch --show-current` with `run_in_background: true` now — result will be ready by the time we need it for git context detection.
 
-1. Show available brands:
-```
-Available brands:
-  • acme-corp (complete — all 4 phases)
-  • beta-labs (in progress — 2/4 phases)
-```
-
-If no brands exist, explain that a brand is needed first and offer to create one.
-If only one complete brand exists, suggest it as default.
-If multiple brands exist, use `AskUserQuestion` with one option per brand (include status in description).
+1. Show available brands with phase status. No brands → offer to create one. One complete → suggest as default. Multiple → `AskUserQuestion` with one option per brand.
 
 2. User selects a brand.
 
@@ -263,27 +206,11 @@ mkdir -p .design/projects/{name}/{brief,research,design,critique,build,review,co
 
 ### Detect git context
 
-Use the git branch detected earlier (run `git branch --show-current` in background at the start of Step 4, while asking for project name — result is ready by now).
+Use the background `git branch --show-current` result. If detected, confirm branch with `AskUserQuestion`. Store in config.json `git.branch` + STATE.md `## Git`. No git repo → skip silently.
 
-1. If a branch was detected, use `AskUserQuestion`: "I see you're on `{branch}` — track this as the project branch?"
-   - **Yes, use this branch** — "Track `{branch}`"
-   - **Different branch** — "I want to use a different branch name"
-3. Store in config.json `git.branch` and STATE.md `## Git` table
-4. If no git repo detected, skip silently — leave fields as "—"
+5. Write `.design/projects/{name}/brand.ref` — brand name, relative path, consumed_at ISO date, identity_hash (first 8 chars md5 of IDENTITY.md, or "pending").
 
-5. Write `brand.ref`:
-```
-brand: {brand-name}
-path: ../../branding/{brand-name}/
-consumed_at: {ISO_DATE}
-identity_hash: {first 8 chars of md5 of IDENTITY.md content, or "pending" if identity not complete}
-```
-Write to `.design/projects/{name}/brand.ref`
-
-6. Consume design system scan results:
-- Read `.design/system/STACK.md` (guaranteed done by now — conversation has been going for multiple rounds)
-- Note classification for config.json
-- Auto-infer `implementation_target` from STACK.md tech stack and COMPONENTS.md component inventory
+6. Consume `.design/system/STACK.md` — note classification for config.json, auto-infer `implementation_target` from STACK.md + COMPONENTS.md.
 
 7. Gather project brief in 2 rounds:
 
@@ -331,33 +258,9 @@ For users who want to skip branding and start designing immediately with a style
 
 ### 5a: Style selection
 
-Read the style presets index at `${CLAUDE_SKILL_DIR}/../../skills/gsp-style/styles/INDEX.yml` and present grouped options:
-
-```
-  ─── pick a style ─────────────────────
-
-  minimal       swiss-minimalist, clean-modern, scandinavian
-  bold          neubrutalism, brutalist, cyberpunk
-  dark          modern-dark, midnight, hacker-terminal
-  editorial     editorial, magazine, newspaper
-  warm          organic, earthy, handcrafted
-  playful       retro-futurism, vaporwave, memphis
-```
-
-Use `AskUserQuestion` with:
-- One option per mood group (showing the first 2-3 preset names as preview)
-- **Surprise me** — "pick something unexpected for my stack"
-
-When user picks a group, show the specific presets in that group with 1-line descriptions from INDEX.yml. Use `AskUserQuestion` to pick the specific preset.
-
-If the user names a preset directly at any point, skip the group step.
+Read `${CLAUDE_SKILL_DIR}/../../skills/gsp-style/styles/INDEX.yml` and present styles grouped by category. Use `AskUserQuestion` with one option per mood group (showing 2-3 preset names as preview) plus **Surprise me**. When user picks a group, drill into specific presets. If user names a preset directly, skip the group step.
 
-**"Surprise me" logic:** Pick a preset weighted by codebase type from the background scan:
-- Developer tools / CLI → dark or minimal presets
-- Content / blog → editorial presets
-- SaaS / dashboard → minimal or bold presets
-- E-commerce → warm or playful presets
-- No codebase detected → truly random pick
+**"Surprise me" logic:** Weight by codebase type — dev tools → dark/minimal, content → editorial, SaaS → minimal/bold, e-commerce → warm/playful, unknown → random.
 
 ### 5b: Create minimal brand