get-shit-pretty 0.6.0 → 0.6.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gsp",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Design engineering system for AI coding agents. Brand identity + design projects, from strategy to code.",
   "author": {
     "name": "jubscodes",

package/README.md

@@ -240,7 +240,7 @@ GSP works across all major AI coding tools. The installer converts Claude Code's
 
 | Feature | Claude Code | OpenCode | Gemini CLI | Codex CLI |
 |---------|:-----------:|:--------:|:----------:|:---------:|
-| Skills | 24 | 24 | 24 | 24 |
+| 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 |
@@ -329,8 +329,7 @@ get-shit-pretty/
 ├── scripts/               Hook scripts and utilities
 ├── gsp/                   Source of truth for all content
 │   ├── agents/            15 subagents (gsp-*.md)
-│   ├── commands/gsp/      20 slash commands (backward compat)
-│   ├── skills/            24 skills (*/SKILL.md — primary)
+│   ├── skills/            30 skills (*/SKILL.md)
 │   ├── hooks/             Plugin-level hooks (hooks.json)
 │   ├── prompts/           12 agent system prompts
 │   ├── templates/         Config, state, brief, roadmap templates
@@ -343,7 +342,7 @@ get-shit-pretty/
 └── CLAUDE.md              AI agent instructions for this repo
 ```
 
-Skills take precedence over commands when both exist. The installer reads from `gsp/` and writes to each runtime's config directory.
+The installer reads from `gsp/` and writes to each runtime's config directory.
 
 ---
 

package/bin/install.js

@@ -915,6 +915,7 @@ function copyOpencodeSkills(srcDir, destDir, pathPrefix) {
     content = content.replace(/\.\/\.claude\//g, './.opencode/');
     content = convertClaudeSkillToOpencode(content, skillName);
     fs.writeFileSync(path.join(skillDest, 'SKILL.md'), content);
+    copySiblingFiles(path.join(srcDir, dir.name), skillDest, pathPrefix);
     count++;
   }
 
@@ -946,6 +947,7 @@ function copyCodexSkillsFromSource(srcDir, destDir, pathPrefix) {
     content = content.replace(/~\/\.claude\//g, pathPrefix);
     content = convertClaudeSkillToCodex(content, skillName);
     fs.writeFileSync(path.join(skillDest, 'SKILL.md'), content);
+    copySiblingFiles(path.join(srcDir, dir.name), skillDest, pathPrefix);
     count++;
   }
   return count;
@@ -986,6 +988,7 @@ function copyGeminiSkills(srcDir, destDir, pathPrefix) {
     content = content.replace(/\.\/\.claude\//g, './.gemini/');
     content = convertClaudeSkillToGemini(content, skillName);
     fs.writeFileSync(path.join(skillDest, 'SKILL.md'), content);
+    copySiblingFiles(path.join(srcDir, dir.name), skillDest, pathPrefix);
     count++;
   }
   return count;
@@ -1030,6 +1033,24 @@ function copyAgents(srcDir, destDir, pathPrefix, runtime, { clean = false } = {}
  * Copy Claude Code skills (global install path — no body conversion, only path replacement).
  * Returns skill count.
  */
+/**
+ * Recursively copy sibling files in a skill directory (everything except SKILL.md).
+ * All sibling files are copied verbatim — no path replacement applied.
+ */
+function copySiblingFiles(srcDir, destDir, pathPrefix) {
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    if (entry.name === 'SKILL.md') continue; // already handled by caller
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copySiblingFiles(srcPath, destPath, pathPrefix);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
 function copyClaudeSkills(srcDir, destDir, pathPrefix) {
   fs.mkdirSync(destDir, { recursive: true });
 
@@ -1045,11 +1066,13 @@ function copyClaudeSkills(srcDir, destDir, pathPrefix) {
     if (!dir.isDirectory()) continue;
     const skillMd = path.join(srcDir, dir.name, 'SKILL.md');
     if (!fs.existsSync(skillMd)) continue;
-    const destSkillDir = path.join(destDir, dir.name);
+    const skillName = dir.name.startsWith('gsp-') ? dir.name : `gsp-${dir.name}`;
+    const destSkillDir = path.join(destDir, skillName);
     fs.mkdirSync(destSkillDir, { recursive: true });
     let content = fs.readFileSync(skillMd, 'utf8');
     content = content.replace(/~\/\.claude\//g, pathPrefix);
     fs.writeFileSync(path.join(destSkillDir, 'SKILL.md'), content);
+    copySiblingFiles(path.join(srcDir, dir.name), destSkillDir, pathPrefix);
     skillCount++;
   }
   return skillCount;

package/gsp/references/questioning.md

@@ -5,10 +5,18 @@ Guide brief-gathering conversations — used by `/gsp:start` for both brand brie
 
 ---
 
+## Core Rules
+
+**One decision per question.** Every question must be its own `AskUserQuestion` call. Never group multiple questions into a single message. Ask one thing, wait for the answer, use it to inform the next question.
+
+**Never re-ask what the user already answered.** If information was gathered in a prior phase and is available in BRIEF.md or other artifacts, use it — don't ask again. If you need to validate stale information, confirm it ("I see X from earlier — still accurate?") rather than asking from scratch. Each phase reads the prior phase's output; the user should never feel like they're repeating themselves.
+
+---
+
 ## Question Flow
 
 ### Phase 1: Context (Who & Why)
-Start broad, then narrow.
+Start broad, then narrow. Each is a separate `AskUserQuestion`.
 
 1. **What** is this project? (app, website, rebrand, campaign)
 2. **Who** is it for? (audience demographics, psychographics)
@@ -41,11 +49,11 @@ Start broad, then narrow.
 
 ## Questioning Techniques
 
-### Progressive Disclosure
-Don't ask all 18 questions at once. Group into 3-4 conversational rounds:
-- Round 1: Context + Brand (questions 1-8)
-- Round 2: Scope + Constraints (questions 9-16)
-- Round 3: Success + Gaps (questions 17-18 + follow-ups)
+### One at a Time
+Ask each question as its own `AskUserQuestion` call. Wait for the answer before asking the next. Use each answer to decide whether to skip, reframe, or drill into the next question.
+
+### Adapt and Skip
+Don't follow the list rigidly. If an early answer reveals enough context, skip later questions. If an answer is surprising, follow up before moving on. The sequence is a guide, not a script.
 
 ### Follow-Up Patterns
 - **"Tell me more about..."** — When an answer is surface-level
@@ -66,9 +74,9 @@ Don't ask what you can infer:
 - Reserve prose questions for open-ended exploration where you genuinely don't know the option space
 
 ### When to Use `AskUserQuestion` vs Prose
-- **Use `AskUserQuestion`** for: picking between defined directions (archetypes, styles, brands), yes/no/which decisions, selecting from existing items (brands, projects), mood/tone/size preferences
-- **Use prose** for: open-ended creative input ("tell me about your brand"), gathering context you can't predict ("what problem does this solve?"), follow-up clarifications where the answer space is unbounded
-- **Rule of thumb:** if you can write 2-4 meaningful options with descriptions, use `AskUserQuestion`. If you'd be guessing at what the options should be, use prose.
+- **Always use `AskUserQuestion`** — this is the default for every user-facing question
+- **Prose is only for** follow-up clarifications where the answer space is truly unbounded and you cannot write meaningful options
+- **Rule of thumb:** if you can write 2-4 meaningful options with descriptions, use `AskUserQuestion`. If you'd be guessing at what the options should be, still use `AskUserQuestion` with an open-ended framing.
 
 ### Knowing When You Have Enough
 A brief is complete when you can answer:

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

@@ -30,6 +30,7 @@ Run lightweight accessibility checks inline — contrast ratio lookups and token
 
 <rules>
 - Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
 - Quick check mode (`--check`) produces display output only — no files written
 - Token audit mode runs inline — no agent spawned
 - Default conformance level is AA unless overridden by `--level AAA` or config

package/gsp/skills/gsp-accessibility-audit/SKILL.md

@@ -37,6 +37,7 @@ Run full accessibility audits — design screen reviews, codebase ARIA/keyboard/
 
 <rules>
 - Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
 - Statement mode reads prior audit results — fails gracefully if none exist
 - Default conformance level is AA unless overridden by `--level AAA` or config
 - Foundation chunks follow `references/chunk-format.md` format

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

@@ -29,6 +29,7 @@ Audit an existing brand. Produce evolution map that guides research, strategy, a
 
 <rules>
 - Always use `AskUserQuestion` for user-facing questions — never raw text prompts
+- One decision per question — never batch multiple questions in a single message
 - Keep interactions concise — gather assets, confirm scope, spawn agent
 - Artifacts must balance human readability with agent consumption for downstream phases
 </rules>
@@ -43,13 +44,15 @@ Read `{BRAND_PATH}/config.json` to confirm `brand_mode` is `evolve`.
 
 If missing, tell user to run `/gsp:start` first.
 
-## Step 2: Gather brand assets
+## Step 2: Load brand assets from brief
 
-Use `AskUserQuestion` to prompt for assets:
+Read `{BRAND_PATH}/BRIEF.md` — brand assets were already gathered during `/gsp:start`. Extract any logos, colors, guidelines, URLs, or descriptions the user provided.
+
+If the brief has no asset information (legacy or incomplete brief), use `AskUserQuestion`:
 - **Share assets now** — "I have guidelines, colors, fonts, voice samples, or URLs to share"
 - **Describe the brand** — "I'll describe it in my own words"
 
-Accept whatever format. Infer from partial info. If URLs provided, use WebFetch. Don't over-ask — work with what's given.
+If URLs were provided (in brief or just now), use WebFetch. Don't re-ask for information already in the brief.
 
 ## Step 3: Spawn auditor
 

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

@@ -31,6 +31,8 @@ Build the brand's visual identity.
 
 <rules>
 - Always use `AskUserQuestion` for user-facing questions — never raw text prompts
+- One decision per question — never batch multiple questions in a single message
+- Never re-ask what the user already answered in a prior phase — read BRIEF.md and strategy chunks, build on them
 - Every visual decision must trace to strategy — archetype, positioning, or voice
 - Artifacts must balance human readability with agent consumption for downstream phases
 </rules>
@@ -75,9 +77,11 @@ Use `AskUserQuestion` with 2-3 visual directions:
 - **Description:** color palette direction, typography feel, overall aesthetic
 - **Preview:** "Palette: {key colors}. Type: {typeface style}. Feel: {1-line vibe}."
 
-After selection, ask for hard constraints or visual references via `AskUserQuestion`:
+## Step 2b: Constraints
+
+After visual direction is confirmed, ask as a separate `AskUserQuestion`:
 - **No constraints** — "Go ahead with this direction"
-- **Add constraints** — "I have specific requirements"
+- **Add constraints** — "I have specific requirements (colors to avoid, accessibility needs, existing assets to match)"
 
 ## Step 3: Spawn identity designer
 

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

@@ -30,6 +30,11 @@ Build the design system, generate brand guidelines, and complete the branding di
 @${CLAUDE_SKILL_DIR}/../../references/design-tokens.md
 </execution_context>
 
+<rules>
+- Always use `AskUserQuestion` for user-facing questions — never raw text prompts
+- One decision per question — never batch multiple questions in a single message
+</rules>
+
 <process>
 ## Step 0: Resolve brand
 
@@ -66,14 +71,20 @@ If `style_base` is empty or missing, load `${CLAUDE_SKILL_DIR}/../gsp-style/styl
 
 **Always scan:** If `.design/system/` docs don't exist, invoke `/gsp:design-system` via Skill tool to scan the codebase. If they already exist, read them. Either way, load STACK.md, COMPONENTS.md, and TOKENS.md before continuing.
 
-Then ask the user:
-1. "Will this brand target a specific tech stack?" (React + Tailwind, React Native + NativeWind, vanilla CSS, etc.)
-   - If the scan detected a stack, present it as the default: "I see you're using {framework} with {styling} — build on that?"
-   - Store answer in `{BRAND_PATH}/config.json` → `system_config.tech_stack`
-2. Based on scan results, determine system strategy:
-   - If scan found existing tokens/components: "You have an existing design system. Want to evolve it, rethink it from scratch, or ignore it?"
-   - Store strategy in `{BRAND_PATH}/config.json` → `system_config.system_strategy`
-   - If scan found no tokens/components (greenfield/boilerplate): default to `generate`, skip the question
+Then ask the user (each as its own `AskUserQuestion`):
+
+1. Tech stack — if the scan detected a stack, use `AskUserQuestion`:
+   - **Yes, build on {framework} + {styling}** — "Use what's already here"
+   - **Different stack** — "I want to target a different tech stack"
+   If no stack detected, use open-ended `AskUserQuestion`: "What tech stack will this brand target?"
+   Store answer in `{BRAND_PATH}/config.json` → `system_config.tech_stack`
+
+2. System strategy — only ask if scan found existing tokens/components. Use `AskUserQuestion`:
+   - **Evolve** — "Extend the existing design system"
+   - **Rethink** — "Redesign from scratch, informed by what exists"
+   - **Ignore** — "Start fresh, don't reference the existing system"
+   Store strategy in `{BRAND_PATH}/config.json` → `system_config.system_strategy`
+   If scan found no tokens/components (greenfield/boilerplate): default to `generate`, skip this question
 
 ## Step 2: Determine system strategy
 
@@ -121,37 +132,37 @@ The agent writes foundations only:
 
 ## Step 3.5: Foundation review (interactive)
 
-Read the foundation outputs and present:
+Read the foundation outputs and present a compact summary:
 
-"Here are the design system foundations:
+"Design system foundations:
  Color: {semantic mapping summary from foundations/color-system.md}
  Typography: {type scale summary from foundations/typography.md}
  Spacing: 8px base → {scale from foundations/spacing.md}
- Design principles: {list from principles.md}
+ Design principles: {list from principles.md}"
 
- Everything right? Adjustments before building components?"
+Use `AskUserQuestion`:
+- **Looks good** — "Build components on these foundations"
+- **Adjust colors** — "I want to tweak the color system"
+- **Adjust typography** — "I want to tweak the type scale"
+- **Adjust other** — "I want to change spacing, principles, or other foundations"
 
-Wait for user input. If adjustments needed, update the relevant foundation chunks.
+If adjustments needed, update the relevant foundation chunks, then re-present.
 
 ## Step 3.75: Perspective check
 
 Before building components, load persona profiles from `{BRAND_PATH}/BRIEF.md` and present stakeholder reactions:
 
-"Before we build the component library on these foundations:
+"Before we build the component library:
 
- The Customer ({primary persona name from BRIEF.md}):
- "{would a user recognize this as {brand}? Does the system feel like the brand?}"
+ {primary persona name}: {would they recognize this as {brand}? Does it feel right?}
+ Skeptic: {are the tokens flexible enough? Are the principles actionable?}
+ {top competitor}: {how does this compare to industry standards?}"
 
- The Skeptic (internal stakeholder):
- "{challenges system decisions — are the tokens flexible enough? Are the principles actionable?}"
+Use `AskUserQuestion`:
+- **Build components** — "These foundations are solid, let's go"
+- **Adjust** — "One of these concerns resonates — I want to change something"
 
- The Competitor ({top competitor name}):
- "{how does this system compare to industry standards? Any gaps?}"
-
- Any of these concerns resonate? Want to adjust foundations before building components?"
-
-If user wants changes → update foundations.
-If confirmed → proceed to components pass.
+If adjust → update foundations and re-present. If confirmed → proceed to components pass.
 
 ## Step 4: Spawn pattern architect — Pass 2: Components
 
@@ -208,7 +219,9 @@ Tell the user: "Brand kit saved to `guidelines.html` — open it in your browser
 
 Render phase transition (see `references/phase-transitions.md`).
 
-**Critical:** When the user chooses "Start a project", invoke `/gsp:start` via the Skill tool. Do NOT attempt to handle project setup inline — `/gsp:start` has the codebase scanning, questioning rounds, and brief-writing logic needed for a proper project setup. The branding agent's context is spent on brand work and lacks the project setup methodology.
+**E2E mode:** Read `{BRAND_PATH}/config.json`. If `e2e` is `true`, auto-invoke `/gsp:start` via Skill tool — it will detect the completed brand and route directly to project setup (Step 4). No need to ask the user.
+
+**Non-E2E:** When the user chooses "Start a project", invoke `/gsp:start` via the Skill tool. Do NOT attempt to handle project setup inline — `/gsp:start` has the codebase scanning, questioning rounds, and brief-writing logic needed for a proper project setup. The branding agent's context is spent on brand work and lacks the project setup methodology.
 
 Also display a brand summary after the standard transition — this is the final branding phase:
 

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

@@ -31,6 +31,7 @@ Accept natural language feedback about brand visuals, identify which tokens are
 
 <rules>
 - Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
 - 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

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

@@ -31,6 +31,7 @@ Research market context that will inform brand strategy.
 
 <rules>
 - Always use `AskUserQuestion` for user-facing questions — never raw text prompts
+- One decision per question — never batch multiple questions in a single message
 - Keep interactions concise — 1-2 exchanges max before spawning the agent
 - Artifacts must balance human readability with agent consumption for downstream phases
 </rules>

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

@@ -32,6 +32,8 @@ Define brand strategy and voice through interactive creative direction, then pro
 
 <rules>
 - Always use `AskUserQuestion` for user-facing questions — never raw text prompts
+- One decision per question — never batch multiple questions in a single message
+- Never re-ask what the user already answered in a prior phase — read BRIEF.md and build on it
 - Push opinionated recommendations but let the user decide
 - Quality gate: if you could swap in a competitor's name and it still works, it's too generic
 - Artifacts must balance human readability with agent consumption for downstream phases
@@ -61,9 +63,11 @@ Frame as: "Here's where this brand can win." Keep it to 4-6 lines.
 
 ## Step 3: Archetype selection
 
-Use `AskUserQuestion` with 2-3 archetype candidates. Each option:
+Read the personality direction from BRIEF.md (gathered during `/gsp:start`). Use it as the starting point — don't re-ask for personality. Deepen it into a structural archetype.
+
+Use `AskUserQuestion` with 2-3 archetype candidates that align with the chosen personality direction. Each option:
 - **Label:** archetype name
-- **Description:** strategic reasoning — why it fits the personas and gaps
+- **Description:** strategic reasoning — why it fits the personas and gaps, and how it builds on the personality direction from the brief
 - **Preview:** example sentence in that archetype's voice
 
 Push a recommendation. Let user choose, adjust, or blend.

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

@@ -37,6 +37,7 @@ Compare a project's shipped state against its source brand across all dimensions
 
 <rules>
 - Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
 - Never update the brand without explicit user confirmation
 - Show before/after for every change — no silent updates
 - Only update dimensions that actually diverged — don't regenerate the entire brand

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

@@ -239,6 +239,22 @@ Glob for all SKILL.md files in the skills directory (`{runtime-dir}/skills/*/SKI
 - All present → PASS
 - Missing → WARN: "Skills missing `user-invocable: true`: {list}. They won't appear in the slash-command menu. Re-run the installer or add the field manually."
 
+**Check I2: Skill directories are complete (not just SKILL.md)**
+For each gsp-* skill directory, check if `SKILL.md` references sibling files via `${CLAUDE_SKILL_DIR}/` paths (e.g. `styles/INDEX.yml`). If it does, verify those files/dirs exist in the installed skill directory.
+- All referenced siblings present → PASS
+- Missing siblings → FAIL: "Skill {name} references {path} but it's missing. Re-run the installer: `npx get-shit-pretty`"
+
+**Check I3: Bundle directories accessible**
+Check that the runtime bundle directories exist (`{runtime-dir}/prompts/`, `{runtime-dir}/templates/`, `{runtime-dir}/references/`). Skills reference these via `${CLAUDE_SKILL_DIR}/../../`.
+- All present → PASS
+- Missing → FAIL: "Bundle directory {dir} missing. Re-run the installer: `npx get-shit-pretty`"
+
+**Check I4: VERSION file present**
+Check `{runtime-dir}/VERSION` exists and contains a valid semver string.
+- Present and valid → PASS (show version)
+- Missing → WARN: "VERSION file missing. Re-run the installer."
+- Mismatched with source → INFO: "Installed version {installed} differs from source {source}."
+
 ### Cross-Instance Checks
 
 **Check X1: Multiple projects, same brand**
@@ -287,6 +303,9 @@ Overall Health: {SCORE}/100 {emoji}
 
 ─── Installation Health ───────────────
   ✅ I1. Skills invocable ........ PASS
+  ✅ I2. Skill completeness ...... PASS
+  ✅ I3. Bundle directories ...... PASS
+  ✅ I4. VERSION file ............ PASS
 
 ─── Cross-Instance ────────────────────
   ✅ X1. Brand Consistency ...... PASS

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

@@ -31,6 +31,7 @@ Generate production-ready OKLCH color palettes from hex colors.
 
 <rules>
 - Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
 - Palettes are deterministic — same hex input always produces the same OKLCH scales
 - Foundation chunks follow `references/chunk-format.md` format exactly
 - Every palette gets the full 11-stop scale: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950

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

@@ -25,7 +25,7 @@ Multiple brands and projects can coexist. Projects reference a brand.
 </context>
 
 <objective>
-Through 2-3 rounds of natural conversation, gather a complete brief and create the right project structure (brand, project, or both). Route the user to their first phase skill.
+Through a sequential one-question-at-a-time conversation, gather a complete brief and create the right project structure (brand, project, or both). Route the user to their first phase skill.
 </objective>
 
 <execution_context>
@@ -49,11 +49,12 @@ Through 2-3 rounds of natural conversation, gather a complete brief and create t
 <questioning_principles>
 Follow these principles throughout all conversations:
 
-1. **Inference over interrogation** — state assumptions, let them correct. "SaaS dashboard for enterprise" → you already know: professional, data-dense, web-first.
-2. **Progressive disclosure** — don't dump all questions at once. Flow in natural rounds.
-3. **Concrete options over open-ended** — "More like Stripe's clean approach or Duolingo's playful style?" beats "What style do you want?"
-4. **Know when you have enough** — fill gaps with smart defaults. Don't over-ask.
-5. **One message per round** — ask a cohesive set of related questions, not one at a time.
+1. **One decision per question** — every question must be its own `AskUserQuestion` call with exactly one decision. Never group multiple questions into a single message. Ask, wait for the answer, then ask the next thing.
+2. **Never re-ask** — if the user already answered something (in this phase or a prior one), don't ask again. If you need to validate, confirm: "I see X from earlier — still accurate?" The user should never feel like they're repeating themselves.
+3. **Inference over interrogation** — state assumptions, let them correct. "SaaS dashboard for enterprise" → you already know: professional, data-dense, web-first.
+4. **Adapt and skip** — use each answer to inform the next question. If an answer reveals enough to skip a later question, skip it. Don't follow a rigid checklist.
+5. **Concrete options over open-ended** — "More like Stripe's clean approach or Duolingo's playful style?" beats "What style do you want?"
+6. **Know when you have enough** — fill gaps with smart defaults. Don't over-ask.
 </questioning_principles>
 
 <process>
@@ -71,7 +72,7 @@ Scan `.design/` for existing brands and projects:
 
 ### Step 1b: Run design system scan (background)
 
-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.
+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 the brand essence questions or Step 4.
 
 ### Step 1c: Greet
 
@@ -121,8 +122,7 @@ Weave in what you found naturally: framework, styling, component count.
 
 From the greeting exchange, determine which flow to run:
 
-- **Brand identity (new)** → Brand flow (Step 3) with `brand_mode: "new"`
-- **Brand identity (evolve)** → Brand flow (Step 3) with `brand_mode: "evolve"`. Detect evolve signals: user mentions existing brand, assets, guidelines, rebrand, refresh, modernize, evolve, update, redesign.
+- **Brand identity** → Brand flow (Step 3)
 - **Design project** → Check for brands first. If none exist, explain they need a brand first. Offer to create one, then auto-transition to project flow.
 - **Full design (brand + project)** → Brand flow (Step 3), with E2E flag so brand completion auto-transitions to project flow (Step 4)
 - **Quick project** → Quick flow (Step 5)
@@ -130,49 +130,69 @@ From the greeting exchange, determine which flow to run:
 
 ## Step 3: Brand flow
 
+Each question is its own `AskUserQuestion` call. Ask one, wait, adapt, ask the next. Skip anything you can already infer.
+
+**Step 3a — Brand name and path selection:**
+
 1. Ask for brand name (kebab-case, e.g., "acme-corp")
-2. Create directory structure:
+2. "Do you already have brand materials to work with?" — use `AskUserQuestion`:
+   - **Yes, I have an existing brand** — "I have a logo, colors, guidelines, or other assets"
+   - **No, starting fresh** — "Building a brand from scratch"
+
+If **yes** → set `brand_mode: "evolve"`. Continue with evolve sequence (Step 3b-evolve).
+If **no** → set `brand_mode: "new"`. Continue with new sequence (Step 3b-new).
+
+3. Create directory structure:
 ```bash
 mkdir -p .design/branding/{name}/{audit,discover,strategy,identity,patterns}
 ```
 
-3. Gather brand brief in 3 rounds. The brief is the single source of truth for business and persona definition — invest here.
+**Step 3b-evolve — Gather existing brand context:**
+
+Ask these before business questions — the existing brand shapes everything:
+
+3. Share your current brand materials — logo, colors, guidelines, URLs, anything you have. (open-ended — gather thoroughly here. Brand-audit will NOT re-ask for assets.)
+4. How old is the current brand? (open-ended)
+5. What's working well with the current brand? (open-ended)
+6. What's not working — what are the pain points? (open-ended)
+7. Evolution scope — use `AskUserQuestion`: **Preserve most, tweak details** / **Evolve significantly, keep core** / **Replace — start fresh**
+
+Then continue to Step 3c (business & people), skipping anything the brand materials already reveal.
+
+**Step 3b-new — Skip to business questions:**
 
-**Round 1 — Business & People:**
-- Company name, industry, stage
-- 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
+Continue directly to Step 3c.
 
-**Round 2 — Brand Essence & Landscape:**
+**Step 3c — Business & People:**
 
-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.
+8. What's the company name, and what industry/stage? (open-ended `AskUserQuestion`)
+9. What problem does it solve, and for whom? (open-ended — use the answer to start inferring persona)
+10. What's the business model? (use `AskUserQuestion` with options if you can infer likely models from industry, otherwise open-ended)
+11. Who are the main competitors? (2-3 names — open-ended)
+12. Present an inferred primary persona — a concrete profile (name, role, frustration, aspiration) based on answers so far. Personas should feel like real people — dig into the emotional layer. Use `AskUserQuestion`: **Looks right** / **Adjust** / **Add a secondary persona**
 
-- 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)
-  - **Surprise me** — craft an unexpected direction inspired by the user's industry and personas
-- What the brand should NEVER feel like
-- Competitive landscape — use `WebSearch` to enrich the competitors named in Round 1. Present the map for confirmation.
-- Brands admired / styles to avoid
+**Step 3d — Brand Essence:**
 
-**Round 3 — Constraints & confirmation:**
-- Existing brand assets? (logo, colors, guidelines)
-- Timeline and budget constraints
-- Non-negotiables
-- **Check background scan:** If the codebase scanner has returned results, weave tech findings naturally.
-- State your understanding back: "Here's what I'm hearing: [summary]." Use `AskUserQuestion`:
-  - **Looks good** — "That's accurate, let's go"
-  - **Adjust something** — "I want to change or add something"
+Before presenting personality options, **internally synthesize** promise (what should someone feel?) and point of view (what does this brand disagree with?) from prior answers. Don't ask these directly — use them to ground personality options.
 
-**Evolve mode additions (when `brand_mode` is `evolve`):**
-Add to Round 3:
-- Current brand age, existing guidelines
-- Brand equity (what's working) and pain points (what's not)
-- Evolution scope — preserve / evolve / replace
+13. Brand personality direction — 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)
+    - **Surprise me** — craft an unexpected direction inspired by the user's industry and personas
+    - Note: this is a high-level direction only. Brand strategy phase will deepen this into archetype + voice — don't over-refine here.
+14. What should the brand NEVER feel like? (use `AskUserQuestion` with 2-3 anti-directions inferred from their personality pick, plus open-ended option)
+15. Brands admired or styles to avoid? (open-ended `AskUserQuestion`)
 
-Skip or compress rounds if the user gives enough upfront. Don't over-ask.
+Note: competitive landscape deep-dive happens in the research phase — don't re-confirm it here. The competitor names from Q11 are enough.
+
+**Step 3e — Constraints & confirmation:**
+
+16. Any non-negotiables or constraints? (timeline, budget, must-haves) — open-ended `AskUserQuestion`
+17. **Check background scan:** If the codebase scanner has returned results, weave tech findings naturally into your summary.
+18. State your understanding back: "Here's what I'm hearing: [summary]." Use `AskUserQuestion`:
+    - **Looks good** — "That's accurate, let's go"
+    - **Adjust something** — "I want to change or add something"
+
+Skip any question you can already answer from prior context. Don't over-ask.
 
 4. Write artifacts:
 - `.design/branding/{name}/BRIEF.md` from brand brief template
@@ -186,8 +206,8 @@ Skip or compress rounds if the user gives enough upfront. Don't over-ask.
 
 - **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)
+- **E2E, new →** continue to `/gsp:brand-research` (complete the entire brand pipeline first — research → strategy → identity → patterns — then auto-transition to Step 4 for project setup). Set `"e2e": true` in config.json so brand-patterns knows to route to project flow after completion.
+- **E2E, evolve →** continue to `/gsp:brand-audit` (complete full brand pipeline, then auto-transition to Step 4). Set `"e2e": true` in config.json.
 
 ## Step 4: Project flow
 
@@ -212,33 +232,31 @@ Use the background `git branch --show-current` result. If detected, confirm bran
 
 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:
-
-**Round 1 — What we're building:**
-- What are we building? (app, website, dashboard, etc.)
-- Present background scan findings: "I found a {classification} {framework} project with {details}. Want to build on that?"
-- Platforms (web, iOS, Android)?
-- Tech stack preferences? (confirm inferred or ask)
-- Implementation target — use `AskUserQuestion` with options based on codebase analysis (e.g., shadcn, rn-reusables, custom, css-only)
-- Design scope — use `AskUserQuestion`:
-  - **Full** — "Complete design: screens, components, tokens"
-  - **Partial** — "Specific screens or flows only"
-  - **Tokens only** — "Just design tokens, no screens"
-- Key screens/flows needed?
-
-Use inference from the codebase scan — don't re-ask what you can already see.
-
-**Round 2 — Success & gaps:**
-- Success criteria
-- Timeline, constraints
-- Any remaining gaps
-- State your understanding back: "Here's what I'm hearing: [summary]." Use `AskUserQuestion`:
-  - **Looks good** — "That's accurate, let's go"
-  - **Adjust something** — "I want to change or add something"
-  - **Explain this** — "Walk me through what you captured and why" → explain each section of the brief and how it'll be used in the next phases
-  - **Surprise me** — "Suggest something I haven't thought of" → propose an unexpected screen, flow, or feature angle that would elevate the project based on what you know about the brand, audience, and codebase. Present it as a suggestion the user can adopt, tweak, or skip.
-
-Skip or compress rounds if the user gives enough upfront. Don't over-ask.
+7. Gather project brief as a sequential conversation. Each question is its own `AskUserQuestion` call. Ask one, wait, adapt, ask the next. Skip anything you can already infer from the codebase scan.
+
+**Sequence — What we're building:**
+
+1. What are we building? (app, website, dashboard, etc.) — open-ended `AskUserQuestion`
+2. Present background scan findings: "I found a {classification} {framework} project with {details}." Use `AskUserQuestion`: **Build on this** / **Different stack** / **Tell me more**
+3. Platforms? — use `AskUserQuestion`: **Web** / **iOS** / **Android** / **Cross-platform** (skip if obvious from codebase)
+4. Implementation target — use `AskUserQuestion` with options based on codebase analysis (e.g., shadcn, rn-reusables, custom, css-only)
+5. Design scope — use `AskUserQuestion`:
+   - **Full** — "Complete design: screens, components, tokens"
+   - **Partial** — "Specific screens or flows only"
+   - **Tokens only** — "Just design tokens, no screens"
+6. Key screens/flows needed? — open-ended `AskUserQuestion`
+
+**Sequence — Success & confirmation:**
+
+7. What does success look like? — open-ended `AskUserQuestion`
+8. Any constraints? (timeline, budget, must-haves) — open-ended `AskUserQuestion`
+9. State your understanding back: "Here's what I'm hearing: [summary]." Use `AskUserQuestion`:
+   - **Looks good** — "That's accurate, let's go"
+   - **Adjust something** — "I want to change or add something"
+   - **Explain this** — "Walk me through what you captured and why" → explain each section of the brief and how it'll be used in the next phases
+   - **Surprise me** — "Suggest something I haven't thought of" → propose an unexpected screen, flow, or feature angle that would elevate the project based on what you know about the brand, audience, and codebase. Present it as a suggestion the user can adopt, tweak, or skip.
+
+Skip any question you can already answer from the codebase scan. Don't over-ask.
 
 8. Write artifacts:
 - `.design/projects/{name}/BRIEF.md` from project brief template
@@ -309,7 +327,7 @@ Continue directly to Step 4 (project flow) with these modifications:
 - Go straight to asking for project name
 - Set `style_preset: "{preset}"` in the project's `config.json`
 - Set `identity_hash: "style-only"` in `brand.ref`
-- Proceed with the normal 2-round project brief gathering
+- Proceed with the normal sequential project brief gathering
 
 ### Upgrade path
 

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

@@ -35,6 +35,7 @@ Apply a named style preset to produce production-ready design tokens and foundat
 
 <rules>
 - Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
 - `tokens.json` follows W3C Design Tokens format from `references/design-tokens.md`
 - When mixing styles, later style values override earlier ones (last-wins precedence)
 - Never mix clashing styles — check the compatibility matrix first

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

@@ -34,6 +34,7 @@ Generate a production-ready typography system with fluid responsive sizing, vert
 
 <rules>
 - Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
 - Foundation chunks follow `references/chunk-format.md` format exactly
 - All sizes include px, rem, AND fluid clamp() values for headings
 - Line heights snap to a 4px grid for vertical rhythm (body 24px = 6 × 4px)

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

@@ -2,36 +2,51 @@
 name: update
 description: Update GSP to the latest version
 user-invocable: true
+allowed-tools:
+  - Read
+  - Bash
+  - AskUserQuestion
+  - Glob
+  - WebFetch
 ---
 <objective>
 Check for GSP updates, show what's new, and run the update if the user confirms.
 </objective>
 
+<rules>
+- Always use `AskUserQuestion` for user-facing questions — never raw text prompts
+- One decision per question — never batch multiple questions in a single message
+</rules>
+
 <process>
 
 ## Step 1 — Detect installation
 
-Check for a `VERSION` file to determine install type. The runtime directory varies by tool:
-- Claude Code: `.claude/` (local) or `~/.claude/` (global)
-- OpenCode: `.opencode/` (local) or `~/.config/opencode/` (global)
-- Gemini: `.gemini/` (local) or `~/.gemini/` (global)
-- Codex: `.codex/` (local) or `~/.codex/` (global)
+Determine the runtime by checking which config directory exists. Check local first, then global:
+
+| Runtime | Local dir | Global dir |
+|---------|-----------|------------|
+| Claude Code | `.claude/` | `~/.claude/` |
+| OpenCode | `.opencode/` | `~/.config/opencode/` |
+| Gemini | `.gemini/` | `~/.gemini/` |
+| Codex | `.codex/` | `~/.codex/` |
 
-Look for the VERSION file in both local and global locations. Check two paths per location (current layout first, legacy fallback):
+For each runtime, look for the VERSION file in two paths (current layout first, legacy fallback):
 1. `{runtime-dir}/VERSION` (v0.5.0+)
 2. `{runtime-dir}/get-shit-pretty/VERSION` (legacy v0.4.x)
 
-If neither exists in either location, tell the user GSP doesn't appear to be installed and suggest running:
+Record which runtime(s) and install type (local/global) were found.
+
+If no VERSION file exists anywhere, tell the user GSP doesn't appear to be installed and suggest:
 ```
 npx get-shit-pretty
 ```
 Then stop.
 
-Read the VERSION file to get the installed version. Store which type was detected (local or global).
+Read the VERSION file to get the installed version.
 
 ## Step 2 — Check latest version
 
-Run:
 ```bash
 npm view get-shit-pretty version
 ```
@@ -40,7 +55,7 @@ If the command fails, tell the user the version check failed (they may be offlin
 
 ## Step 3 — Compare versions
 
-If installed version >= latest version, tell the user:
+If installed version >= latest version:
 ```
 GSP v{installed} is already up to date.
 ```
@@ -48,40 +63,55 @@ Then stop.
 
 ## Step 4 — Show what's new
 
-Tell the user:
 ```
 Update available: v{installed} → v{latest}
 ```
 
-Fetch the changelog to show what changed:
+Fetch the changelog:
 ```bash
 curl -sf https://raw.githubusercontent.com/jubscodes/get-shit-pretty/main/CHANGELOG.md
 ```
 
-If the fetch succeeds, extract and display the section for the latest version. If it fails, skip — changelog display is optional.
+If the fetch succeeds, extract and display the section(s) between the installed and latest versions. If it fails, skip — changelog display is optional.
 
 ## Step 5 — Warn about clean install
 
-Tell the user:
 ```
 The update replaces:
-  • skills/gsp-*       (all GSP skills)
-  • get-shit-pretty/*  (runtime files)
-  • gsp-* agents       (all GSP agents)
+  • skills/gsp-*          (all GSP skills + sibling files)
+  • prompts/              (agent system prompts)
+  • templates/            (config, state, brief templates)
+  • references/           (shared reference material)
+  • agents/gsp-*          (all GSP agents)
 
 Custom files outside these prefixes are preserved.
 ```
 
 ## Step 6 — Confirm with user
 
-Ask the user to confirm before proceeding. If they decline, stop.
+Use `AskUserQuestion`:
+- **Update now** — "Install v{latest}"
+- **Skip** — "I'll update later"
+
+If skip → stop.
 
 ## Step 7 — Execute update
 
-Based on the detected install type from Step 1:
+Build the installer command based on what was detected in Step 1:
+
+**Runtime flag:** use the detected runtime (`--claude`, `--opencode`, `--gemini`, `--codex`). If multiple runtimes were found, use `--all`.
+
+**Scope flag:** `--local` if local install was detected, `--global` if global.
+
+```bash
+npx get-shit-pretty@latest {runtime-flag} {scope-flag}
+```
 
-- **Local install**: run `npx get-shit-pretty@latest --claude --local`
-- **Global install**: run `npx get-shit-pretty@latest --claude`
+Examples:
+- Local Claude: `npx get-shit-pretty@latest --claude --local`
+- Global Claude: `npx get-shit-pretty@latest --claude --global`
+- Global OpenCode: `npx get-shit-pretty@latest --opencode --global`
+- Multiple runtimes: `npx get-shit-pretty@latest --all --global`
 
 Show the output to the user.
 
@@ -102,10 +132,9 @@ rm -f {runtime-dir}/get-shit-pretty/.update-cache.json
 
 ## Step 9 — Remind to restart
 
-Tell the user:
 ```
 GSP updated to v{latest}.
-Restart your Claude Code session to load the new commands and agents.
+Restart your session to load the new skills and agents.
 ```
 
 </process>

package/gsp/templates/branding/config.json

@@ -6,6 +6,7 @@
     "created": ""
   },
   "brand_mode": "new",
+  "e2e": false,
   "evolution_scope": {
     "preserve": [],
     "evolve": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-pretty",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Design engineering system for AI coding agents. Brand identity + design projects, from strategy to code.",
   "bin": {
     "get-shit-pretty": "bin/install.js"