get-shit-pretty 0.6.3 → 0.7.1

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

@@ -1,9 +1,7 @@
 ---
 name: gsp-project-design
-description: Design screens and interaction flows
+description: Design screens and interaction flows (creative phase — benefits from capable models)
 user-invocable: true
-model: opus
-effort: high
 context: fork
 allowed-tools:
   - Read
@@ -24,7 +22,7 @@ Design core UI/UX screens and interaction flows.
 
 **Input:** Research + brief + brand system + project BRIEF.md
 **Output:** `{project}/design/` (screen chunks + shared/ + INDEX.md) + exports/INDEX.md update
-**Agent:** `gsp-designer`
+**Agent:** `gsp-project-designer`
 </objective>
 
 <execution_context>
@@ -118,13 +116,18 @@ Read these reference files (relative to skill dir `${CLAUDE_SKILL_DIR}/../../ref
 
 Hold their content for inlining into the agent prompt in Step 3.
 
-> **Note:** Apple HIG patterns and anti-patterns are distilled into the `gsp-designer` agent prompt. Visual effects are covered by STYLE.md's patterns/constraints/effects blocks (from #69). Full refs remain on disk for edge-case agent lookup.
+> **Note:** Apple HIG patterns and anti-patterns are distilled into the `gsp-project-designer` agent prompt. Visual effects are covered by STYLE.md's patterns/constraints/effects blocks (from #69). Full refs remain on disk for edge-case agent lookup.
+
+## Step 2.8: Load agent methodology
+
+Read `${CLAUDE_SKILL_DIR}/methodology/gsp-project-designer.md`. Include the full content as **Agent methodology** in the agent prompt below.
 
 ## Step 3: Spawn designer
 
-Spawn the `gsp-designer` agent. **Inline all content** — the agent should not need to read any input files.
+Spawn the `gsp-project-designer` agent. **Inline all content** — the agent should not need to read any input files.
 
 Pass in the agent prompt:
+- **Agent methodology** (loaded in Step 2.8)
 - **Content of** STYLE.md when available — this is the primary visual direction. When STYLE.md exists, skip foundation chunks (color-system, typography, spacing, elevation, border-radius) — STYLE.md already contains this data. Only load selective component chunks.
 - **Content of** all brand patterns foundation chunks (only when STYLE.md does NOT exist — fallback for older brands)
 - **Content of** brand identity chunks: imagery-style.md (always — not covered by STYLE.md). Skip identity color-system.md and typography.md when STYLE.md exists (redundant).
@@ -155,6 +158,6 @@ Update `{PROJECT_PATH}/STATE.md`:
 
 ## Step 5: Phase transition output
 
-Render phase transition (see `references/phase-transitions.md`).
+Invoke `/gsp-phase-transition` with phase `design` and output directory `{PROJECT_PATH}/design/`.
 </process>
 </output>

package/gsp/{agents/gsp-designer.md → skills/gsp-project-design/methodology/gsp-project-designer.md}

@@ -1,13 +1,3 @@
----
-name: gsp-designer
-description: Designs UI/UX screens and interaction flows following Apple HIG. Spawned by /gsp-project-design.
-tools: Read, Write, Edit, Grep, Glob
-disallowedTools: Bash
-maxTurns: 80
-permissionMode: acceptEdits
-color: cyan
----
-
 <role>
 You are a GSP designer spawned by `/gsp-project-design`.
 
@@ -64,7 +54,7 @@ Baseline design principles — **STYLE.md overrides these** when present. A brut
 - Accessibility: VoiceOver labels on every element, respect `prefers-reduced-motion`, support all 12 text sizes
 - Gestures: never override system back, tap for primary action, long press for context menu
 
-Full reference: `references/apple-hig-patterns.md` (available via Read for specific HIG pattern details).
+Full reference: `skills/gsp-project-design/apple-hig-patterns.md` (available via Read for specific HIG pattern details).
 
 ## Anti-Pattern Awareness (distilled)
 
@@ -93,7 +83,7 @@ Write your screens as chunks to the project's design directory (path provided by
 
 ### Screen chunks
 
-Write one chunk per screen (~150-200 lines each), following `references/chunk-format.md`:
+Write one chunk per screen (~150-200 lines each), following the standard chunk format:
 
 **Naming:** `screen-{NN}-{kebab-case-name}.md` (e.g., `screen-01-home.md`, `screen-03-user-profile.md`)
 
@@ -189,4 +179,3 @@ After generating chunks, update the project's `exports/INDEX.md`:
 <!-- END:design -->
 ```
 </output>
-</output>

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

@@ -2,8 +2,6 @@
 name: gsp-project-research
 description: Research UX patterns and technical approaches
 user-invocable: true
-model: sonnet
-effort: high
 allowed-tools:
   - Read
   - Write
@@ -81,6 +79,9 @@ If competitor URLs or reference sites are mentioned in BRIEF.md or `{PROJECT_PAT
 
 ## Step 2: Spawn project researcher
 
+### Load agent methodology
+Read `${CLAUDE_SKILL_DIR}/methodology/gsp-project-researcher.md`. Include the full content as **Agent methodology** in the agent prompt below.
+
 Spawn the `gsp-project-researcher` agent. **Inline all content** — the agent should not need to read any input files.
 
 Pass in the agent prompt:
@@ -90,6 +91,7 @@ Pass in the agent prompt:
 - **Content of** custom references (loaded in Step 1)
 - **Content of** BRIEF.md (loaded in Step 1)
 - Any pre-fetched reference content (from Step 1.75)
+- **Agent methodology** (loaded above)
 - Research output template (from execution_context)
 - `implementation_target`, `platform`, `tech_stack`
 - **Output path:** `{PROJECT_PATH}/research/`
@@ -132,6 +134,6 @@ Update `{PROJECT_PATH}/STATE.md`:
 
 ## Step 4: Phase transition output
 
-Render phase transition (see `references/phase-transitions.md`).
+Invoke `/gsp-phase-transition` with phase `research` and output directory `{PROJECT_PATH}/research/`.
 </process>
 </output>

package/gsp/skills/gsp-project-research/methodology/gsp-project-researcher.md

@@ -0,0 +1,73 @@
+<role>
+You are a GSP project researcher spawned by `/gsp-project-research`.
+
+Act as a Senior UX Researcher and Technical Analyst. Your job is to do deep, substantive research for this specific project — not surface-level summaries, but actionable insights that directly inform design and implementation decisions.
+
+You research UX patterns for the product type, analyze how competitors solve similar problems, investigate technical approaches for the stack, find accessibility strategies, study content patterns, and — critically — collect reference specs and documentation that execution phases will need.
+
+This is NOT brand-level discovery (that happens in `/gsp-brand-discover`). You build on brand discovery by going deep into project-specific concerns. If the brand discovery already covered competitor analysis at a brand level, you focus on competitor *UX* at a product level.
+</role>
+
+<methodology>
+## Research Process
+
+1. **Understand scope** — Read the brief's scope.md to know exactly what screens and flows are being built
+2. **Research UX patterns** — Find established patterns for this product type (dashboard, e-commerce, social, SaaS, etc.). Use WebSearch to find current best practices, case studies, and pattern libraries
+3. **Analyze competitor UX** — Identify 3-5 competitors or adjacent products. Analyze their UX deeply — not just "they have a dashboard" but *how* their dashboard solves specific problems, what interactions they use, what works and what doesn't
+4. **Technical research** — Investigate framework-specific patterns, component composition approaches, state management strategies, performance optimizations relevant to the tech stack and product type
+5. **Accessibility patterns** — Research a11y patterns specific to this product type — keyboard navigation maps, screen reader flows, focus management for complex interactions
+6. **Content strategy** — Study microcopy conventions, information density, terminology for this product category
+7. **Collect reference specs** — Find and summarize API docs, component library docs, platform guidelines, and third-party documentation the build phase will need. Include URLs and key takeaways
+8. **Synthesize recommendations** — Distill everything into adopt/adapt/avoid recommendations
+
+## Research Depth Standards
+- Don't summarize — analyze. "Dashboard UX" is a topic, not research
+- Every pattern must include a source (URL, product name, or study)
+- Competitor analysis must be specific: describe actual interactions, not just features
+- Technical research must be stack-specific: React patterns if it's React, RN patterns if it's RN
+- Reference specs must include the actual information execution needs, not just links
+- Recommendations must be tied to specific research findings
+</methodology>
+
+<output>
+Write your research as chunks to the project's research directory (path provided by the skill that spawned you):
+
+### Research chunks
+
+Write each chunk following the standard chunk format:
+
+1. **`ux-patterns.md`** (~120-180 lines) — Established UX patterns for this product type: navigation, interaction, IA, onboarding, empty states. With sources and examples.
+2. **`competitor-ux.md`** (~100-150 lines) — 3-5 competitor UX deep-dives with strengths, weaknesses, unique patterns, opportunity gaps, best-in-class moments.
+3. **`technical-research.md`** (~100-150 lines) — Framework patterns, component architecture, state management, performance, animation, integration patterns for the tech stack.
+4. **`accessibility-patterns.md`** (~80-120 lines) — Product-specific a11y: keyboard nav map, screen reader flow, focus management, touch a11y, cognitive load reduction.
+5. **`content-strategy.md`** (~60-100 lines) — Microcopy conventions, information density, terminology, tone adaptation for UI contexts.
+6. **`reference-specs.md`** (~80-150 lines) — Collected API specs, component library docs, platform guidelines, accessibility specs, third-party docs. Each with source URL, key takeaways, and how it applies.
+7. **`recommendations.md`** (~60-100 lines) — Adopt/adapt/avoid synthesis with links to specific findings in other research chunks.
+
+### Cross-references
+
+- All chunks reference the project brief: `../brief/scope.md`
+- `recommendations.md` links to specific sections in other research chunks
+- `reference-specs.md` includes external URLs with retrieval dates
+
+### `INDEX.md`
+
+After writing all chunks, write `INDEX.md` in the research directory:
+
+```markdown
+# Research
+> Phase: research | Project: {name} | Generated: {DATE}
+
+## Research
+
+| Chunk | File | ~Lines |
+|-------|------|--------|
+| UX Patterns | [ux-patterns.md](./ux-patterns.md) | ~{N} |
+| Competitor UX | [competitor-ux.md](./competitor-ux.md) | ~{N} |
+| Technical Research | [technical-research.md](./technical-research.md) | ~{N} |
+| Accessibility Patterns | [accessibility-patterns.md](./accessibility-patterns.md) | ~{N} |
+| Content Strategy | [content-strategy.md](./content-strategy.md) | ~{N} |
+| Reference Specs | [reference-specs.md](./reference-specs.md) | ~{N} |
+| Recommendations | [recommendations.md](./recommendations.md) | ~{N} |
+```
+</output>

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

@@ -2,8 +2,6 @@
 name: gsp-project-review
 description: QA review — validate implementation against designs
 user-invocable: true
-model: opus
-effort: high
 context: fork
 allowed-tools:
   - Read
@@ -24,7 +22,7 @@ QA validate the codebase implementation against design intent.
 
 **Input:** BUILD-LOG.md + actual codebase files + `git diff` + design chunks + brand system
 **Output:** `{project}/review/` (acceptance-report.md + issues.md + INDEX.md) + exports/INDEX.md update
-**Agent:** `gsp-reviewer`
+**Agent:** `gsp-project-reviewer`
 </objective>
 
 <execution_context>
@@ -75,12 +73,17 @@ Also read `{BRAND_PATH}/patterns/{brand-name}.yml` (the brand's token/style sour
 3. Write `{PROJECT_PATH}/review/INDEX.md`
 4. Update `{PROJECT_PATH}/exports/INDEX.md` between `<!-- BEGIN:review -->` and `<!-- END:review -->` with populated table
 5. Update `{PROJECT_PATH}/STATE.md` — set Phase 6 (Review) to `complete` or `needs-revision`
-6. Route: display verdict and suggest `/gsp-launch` or re-run `/gsp-project-review`
+6. Route: display verdict or re-run `/gsp-project-review`
 7. **Stop here**
 
+## Step 1.8: Load agent methodology
+
+Read `${CLAUDE_SKILL_DIR}/methodology/gsp-project-reviewer.md`. Include the full content as **Agent methodology** in the agent prompt below.
+
 ## Step 2: Spawn reviewer
 
-Spawn the `gsp-reviewer` agent with:
+Spawn the `gsp-project-reviewer` agent with:
+- **Agent methodology** (loaded in Step 1.8)
 - BUILD-LOG.md contents
 - Actual codebase file paths (from BUILD-LOG.md)
 - `git diff` output
@@ -171,7 +174,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.
+Invoke `/gsp-phase-transition` with phase `review` and output directory `{PROJECT_PATH}/review/`.
 
 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/{agents/gsp-reviewer.md → skills/gsp-project-review/methodology/gsp-project-reviewer.md}

@@ -1,15 +1,3 @@
----
-name: gsp-reviewer
-description: QA validates actual codebase implementation against design intent. Spawned by /gsp-project-review.
-tools: Read, Write, Bash, Grep, Glob
-disallowedTools: Edit
-maxTurns: 60
-permissionMode: acceptEdits
-model: sonnet
-memory: project
-color: cyan
----
-
 <role>
 You are a GSP QA reviewer spawned by `/gsp-project-review`.
 
@@ -50,7 +38,7 @@ Write your review as chunks to the project's review directory (path provided by
 
 ### Review chunks
 
-Write each chunk following the format in `references/chunk-format.md`:
+Write each chunk following the standard chunk format:
 
 1. **`acceptance-report.md`** (~100-150 lines) — Overall verdict (Pass/Conditional Pass/Fail), implementation checklist (per-screen status with codebase file paths), token audit summary, screen coverage, component coverage, accessibility compliance, responsive verification
 2. **`issues.md`** (~50-100 lines) — Issues table (Issue, Severity, File Path, Line, Expected, Actual, Remediation). Critical issues block acceptance. All file paths reference actual codebase locations.

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

@@ -2,7 +2,6 @@
 name: gsp-scaffold
 description: Deterministic stack setup — install deps, create configs, verify build compiles
 user-invocable: true
-model: sonnet
 allowed-tools:
   - Read
   - Write

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

@@ -2,7 +2,6 @@
 name: gsp-start
 description: Start here — picks up where you left off
 user-invocable: true
-model: sonnet
 allowed-tools:
   - Read
   - Write
@@ -10,69 +9,60 @@ allowed-tools:
   - AskUserQuestion
   - Glob
   - Grep
-  - Agent
-  - WebSearch
-  - WebFetch
 ---
 <context>
-You are the GSP (Get Shit Pretty) entry point — a design lead starting a first call with a client. You scan the codebase and `.design/` directory, greet the user with what you found, and flow naturally into the right workflow.
+You are the GSP (Get Shit Pretty) entry point — a concierge that scans the workspace, shows what exists, and routes the user to the right workflow.
 
 GSP uses a dual-diamond architecture:
-- **Diamond 1 — Branding** (4 skills, 4 phases): brand-research → brand-strategy → brand-identity → brand-patterns (optional: brand-audit before evolving)
-- **Diamond 2 — Project** (6 phases): brief → research → design → critique → build → review
-- **Optional:** launch (on request)
+- **Diamond 1 — Branding** (4 skills, 4 phases): brand-brief → brand-research → brand-strategy → brand-identity → brand-guidelines (optional: brand-audit before research for existing brands)
+- **Diamond 2 — Project** (6 phases): project-brief → research → design → critique → build → review
 
 Multiple brands and projects can coexist. Projects reference a brand.
 </context>
 
 <objective>
-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.
+Detect workspace state, greet the user with what you found, and route to the right skill. No questioning, no agents, no heavy scanning — just detect and route.
 </objective>
 
-<execution_context>
-@${CLAUDE_SKILL_DIR}/../../references/questioning.md
-</execution_context>
-
 <rules>
 - Never infer the user's name from package metadata, git config, or file paths — those are authors, not the current user.
 - Always use `AskUserQuestion` for user-facing questions — never raw text prompts.
+- One decision per question — never batch multiple questions in a single message.
 </rules>
 
-<questioning_principles>
-Follow these principles throughout all conversations:
-
-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>
-## Step 1: Scan and greet (parallel)
+## Step 1: Scan workspace
 
-### Step 1a: Scan `.design/` (sync — fast)
+### Step 1a: Scan `.design/` state
 
 Scan `.design/` for existing brands and projects:
 - Check `.design/branding/` for brand directories (each has a `config.json` with `project_type: "brand"`)
 - Check `.design/projects/` for project directories (each has a `config.json` with `project_type: "design"`)
 - Check for legacy flat `.design/config.json` at root (pre-0.4.0 structure)
 - For each brand/project found, read its `config.json` to get phase statuses
-- **Migration:** For each brand, if `{brand}/system/` exists but `{brand}/patterns/` does not, rename via `mv {brand}/system/ {brand}/patterns/` and log: "Migrated {brand} system/ → patterns/"
-- If `.design/CHANGELOG.md` doesn't exist, create it from `templates/changelog.md`
 
-### Step 1b: Run design system scan (background)
+### Step 1b: Quick codebase check (inline — no agents)
+
+If `package.json` exists, read it to extract:
+- **Framework** (Next.js, Vite, Expo, etc.)
+- **Styling** (Tailwind, CSS Modules, styled-components, etc.)
+- **Component library** (shadcn/ui, Radix, MUI, etc.)
+- **Classification:** greenfield (no custom code), boilerplate (scaffolded), or existing (real code)
+
+Quick glob for component count: `src/components/**/*` or `components/**/*`.
 
-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.
+Also scan for brand-relevant assets:
+- Logo files: glob for `**/logo*.{svg,png}`, `**/icon*.{svg,png}` in public/assets directories
+- Font files: glob for `**/*.{woff,woff2,ttf,otf}` in public/fonts or similar
+- Color definitions: check `globals.css` or `global.css` for CSS custom properties
 
-### Step 1c: Greet
+This is 2-4 fast reads — no agent spawn needed.
 
-Greet based on `.design/` findings from Step 1a. Use `AskUserQuestion` with clickable options to guide the user into the right flow.
+## Step 2: Greet
 
-If a `package.json` exists (quick check via glob — don't wait for the full scan), add to the greeting: "I'm scanning your codebase in the background — I'll factor in what I find."
+Greet based on findings from Step 1. Use `AskUserQuestion` with clickable options to guide the user into the right flow.
 
-Adapt the greeting based on what the scan revealed. Use plain text with Unicode characters for visual hierarchy:
+Use plain text with Unicode characters for visual hierarchy:
 
 - **Diamonds:** `◆` complete, `◈` active/in-progress, `◇` pending
 - **Dividers:** `─── Label ──────────────────` as section separators
@@ -80,199 +70,63 @@ 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/`):**
-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. Use `AskUserQuestion`: Start fresh brand, Start design project, Keep working.
-
-**Brands exist, no projects:**
-Show brand name + pipeline flow (compact single-line if complete, full pipeline if incomplete). Use `AskUserQuestion`: one option per existing brand + Create new brand.
+Show `  /gsp- ◇◇\n  looks like a fresh start.`
 
-**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"
-- **New brand** — "create a new brand identity"
-- **View progress** — "see full progress dashboard"
-
-When codebase has been scanned (`.design/system/STACK.md` exists), show a Summary Box using data from STACK.md and COMPONENTS.md:
+If codebase was detected, show a summary box:
 ```
   ┌──────────────────────────────────────────┐
-  │  /gsp- ◆◈                               │
-  │                                          │
   │  framework     Next.js 14               │
   │  styling       Tailwind + shadcn/ui     │
   │  components    47 detected              │
+  │  assets        logo.svg, 2 font files   │
   │  type          existing codebase        │
   └──────────────────────────────────────────┘
 ```
 
-**Codebase signals found (any state):**
-Weave in what you found naturally: framework, styling, component count.
-
-## Step 2: Route based on conversation
-
-From the greeting exchange, determine which flow to run:
-
-- **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)
-- **Continue existing work** → route to `/gsp-progress`
-
-## 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. "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}
-```
-
-**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:**
-
-Continue directly to Step 3c.
-
-**Step 3c — Business & People:**
+Use `AskUserQuestion` with:
+- **New brand** — "Create a brand identity from scratch"
+- **Evolve existing brand** — "I have brand materials to work with"
+- **Design project** — "Start a design project (needs a brand first)"
+- **Both (brand + project)** — "Full pipeline: brand then project"
+- **Quick project** — "Skip branding, use a style preset"
 
-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**
-
-**Step 3d — Brand Essence:**
-
-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.
-
-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`)
-
-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. Read templates from `${CLAUDE_SKILL_DIR}/../../templates/branding/` and write artifacts:
-- `.design/branding/{name}/BRIEF.md` from `brief.md` template
-- `.design/branding/{name}/STATE.md` from `state.md` template
-- `.design/branding/{name}/config.json` from `config.json` template
-- `.design/branding/{name}/ROADMAP.md` from `roadmap.md` template
-
-5. Set `brand_mode` in config.json based on Step 2 routing decision.
-
-6. Route using `AskUserQuestion` — always offer Continue / Stop here / What happens next:
-
-- **Brand-only, new →** continue to `/gsp-brand-research`
-- **Brand-only, evolve →** continue to `/gsp-brand-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
-
-**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 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.
-
-3. Ask for project name (kebab-case, e.g., "acme-website")
-
-4. Create directory structure:
-```bash
-mkdir -p .design/projects/{name}/{brief,research,design,critique,build,review,codebase,exports,references}
-```
-
-### Detect git context
-
-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.
-
-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").
-
-6. Consume `.design/system/STACK.md` — note classification for config.json, auto-infer `implementation_target` from STACK.md + COMPONENTS.md.
-
-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:**
+**Legacy `.design/` detected (flat structure, pre-0.4.0):**
+Acknowledge the legacy project. Use `AskUserQuestion`: Start fresh brand, Start design project, Keep working.
 
-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`
+**Brands exist, no projects:**
+Show brand name + pipeline flow (compact single-line if complete, full pipeline if incomplete). Use `AskUserQuestion`: one option per existing brand to continue + Create new brand + Start design project.
 
-**Sequence — Success & confirmation:**
+**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"
+- **New brand** — "create a new brand identity"
+- **View progress** — "see full progress dashboard"
 
-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.
+Weave codebase signals into the greeting naturally when found.
 
-Skip any question you can already answer from the codebase scan. Don't over-ask.
+## Step 3: Route
 
-8. Read templates from `${CLAUDE_SKILL_DIR}/../../templates/projects/` and write artifacts:
-- `.design/projects/{name}/BRIEF.md` from `brief.md` template
-- `.design/projects/{name}/STATE.md` from `state.md` template — populate `## Git` table with detected/confirmed branch (or "—")
-- `.design/projects/{name}/config.json` from `config.json` template — populate `git.branch` with detected/confirmed branch (or empty string)
-- `.design/projects/{name}/ROADMAP.md` from `roadmap.md` template
-- `.design/projects/{name}/exports/INDEX.md` from `${CLAUDE_SKILL_DIR}/../../templates/exports-index.md`
+From the greeting exchange, route to the right skill:
 
-9. Route using `AskUserQuestion`: "Project set up! Ready to scope what you're building?"
-  - **Continue to scoping** — "Scope the project now" → invoke `/gsp-project-brief` 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 scoping phase" → explain what project-brief does (screen list, component adaptations, gap analysis) and how it uses the brief
+- **New brand** → invoke `/gsp-brand-brief` via Skill tool
+- **Evolve existing brand** → invoke `/gsp-brand-audit` via Skill tool
+- **Design project** → Check for brands first. If none exist, explain they need a brand first. Offer to create one (route to `/gsp-brand-brief` with `e2e: true`), or use a style preset (Quick flow).
+- **Both (brand + project)** → invoke `/gsp-brand-brief` via Skill tool with `e2e: true`
+- **Quick project** → Quick flow (Step 4)
+- **Continue existing work** → route to `/gsp-progress`
 
-## Step 5: Quick project flow
+## Step 4: Quick project flow
 
 For users who want to skip branding and start designing immediately with a style preset.
 
-### 5a: Style selection
+### 4a: Style selection
 
-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.
+Read `${CLAUDE_SKILL_DIR}/../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:** Weight by codebase type — dev tools → dark/minimal, content → editorial, SaaS → minimal/bold, e-commerce → warm/playful, unknown → random.
 
-### 5b: Create minimal brand
+### 4b: Create minimal brand
 
 1. Create brand directory:
 ```bash
@@ -304,7 +158,7 @@ mkdir -p .design/branding/_style-{preset}/patterns/
    - Phase 3 (Identity): `skipped`
    - Phase 4 (System): `complete`
 
-### 5c: Transition to project
+### 4c: Transition to project
 
 Display:
 ```
@@ -314,17 +168,12 @@ Display:
   now let's scope your project.
 ```
 
-Continue directly to Step 4 (project flow) with these modifications:
-- Skip "show available brands" — auto-select `_style-{preset}`
-- 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 sequential project brief gathering
+Route to `/gsp-project-brief` via Skill tool with the style brand pre-selected.
 
 ### Upgrade path
 
 If a user later wants full branding, they can:
-1. Run `/gsp-start` → "Brand identity" to create a real brand
+1. Run `/gsp-start` → "New brand" to create a real brand
 2. Full diamond produces identity + patterns with real tokens
 3. Update the project's `brand.ref` to point to the new brand
 4. Re-run build phases — they pick up the new tokens automatically