get-shit-pretty 0.5.2 → 0.6.1

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

@@ -0,0 +1,219 @@
+---
+name: accessibility-audit
+description: Full WCAG accessibility audit — design screens, codebase, or generate compliance statement
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Agent
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<context>
+Full accessibility audit skill that spawns the `gsp-accessibility-auditor` agent for deep WCAG analysis. Works two ways:
+1. **Standalone** — user runs `/gsp:accessibility-audit` directly for design, code, or statement generation
+2. **As a building block** — critique and review phases detect prior accessibility output and reuse it
+
+For quick contrast checks or token audits, use `/gsp:accessibility` instead.
+
+Follows the composable pattern: deterministic modes, predictable output paths, filesystem as integration layer.
+</context>
+
+<objective>
+Run full accessibility audits — design screen reviews, codebase ARIA/keyboard/semantic checks, or compliance statement generation.
+
+**Input:** Mode flag + optional arguments
+**Output:** Audit chunks and fix lists in the appropriate project directory
+**Agent:** `gsp-accessibility-auditor` (for design and code modes), inline for statement
+</objective>
+
+<execution_context>
+@${CLAUDE_SKILL_DIR}/../../prompts/08-accessibility-auditor.md
+@${CLAUDE_SKILL_DIR}/../../references/wcag-checklist.md
+</execution_context>
+
+<rules>
+- Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
+- 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
+</rules>
+
+<process>
+## Step 1: Parse invocation
+
+Read `$ARGUMENTS` to determine the mode:
+
+| Input | Mode | Agent? | Output |
+|-------|------|--------|--------|
+| (no args) | Design audit on `.design/` chunks | Yes (`gsp-accessibility-auditor`) | `critique/accessibility-audit.md` + `accessibility-fixes.md` |
+| `--code` | Codebase audit: ARIA, keyboard, semantic HTML | Yes (`gsp-accessibility-auditor`) | `review/accessibility-audit.md` + `accessibility-fixes.md` |
+| `--statement` | Generate accessibility statement from prior audits | No (inline) | `exports/accessibility-statement.md` |
+
+Additional flag: `--level AAA` overrides conformance level (default: AA).
+
+## Step 2: Resolve context
+
+Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
+
+Read `{PROJECT_PATH}/config.json` to get:
+- `accessibility_level` — override conformance level (if not set via `--level` flag)
+- `implementation_target` — needed for code mode
+
+Read `{PROJECT_PATH}/brand.ref` to resolve brand path:
+- Set `BRAND_PATH` = `.design/branding/{brand}`
+
+Determine final conformance level:
+1. `--level` flag (highest priority)
+2. `accessibility_level` from config.json
+3. Default: "WCAG 2.2 AA"
+
+## Step 3: Design audit mode (default, no flags)
+
+Verify design chunks exist:
+- Read `{PROJECT_PATH}/design/INDEX.md` to find screen chunks
+- If no design chunks, tell user to complete design phase first and stop
+
+### Spawn agent
+
+Spawn `gsp-accessibility-auditor` with:
+- All design chunks from `{PROJECT_PATH}/design/`
+- Brand identity context (color system, typography)
+- Brand system context (tokens, components)
+- Conformance level
+- WCAG checklist reference
+- **Output path:** `{PROJECT_PATH}/critique/`
+- **Instructions:** "Audit all design screens against {level}. Write `accessibility-audit.md` and `accessibility-fixes.md` to the output path."
+
+### Completion
+
+Display result:
+
+```
+  /gsp:accessibility-audit — design audit complete
+  ═══════════════════════════════════════
+
+  {PROJECT_PATH}/critique/
+  ├── accessibility-audit.md
+  └── accessibility-fixes.md
+
+  ─────────────────────────────────────
+```
+
+Use `AskUserQuestion`:
+- **Run token audit** — "run `/gsp:accessibility --tokens` to check design token contrast pairs"
+- **Continue to build** — "implement designs in the codebase"
+- **View audit** — "read the accessibility report"
+- **Done** — "that's all for now"
+
+## Step 4: Code audit mode (`--code`)
+
+Determine codebase scope:
+- Read `{PROJECT_PATH}/config.json` for `implementation_target`
+- If build phase completed, read `{PROJECT_PATH}/build/BUILD-LOG.md` for file paths
+- Otherwise, use `implementation_target` to determine where to look
+
+### Spawn agent
+
+Spawn `gsp-accessibility-auditor` with:
+- Codebase paths to audit
+- Brand system tokens (for contrast verification against hardcoded values)
+- Conformance level
+- WCAG checklist reference
+- **Output path:** `{PROJECT_PATH}/review/`
+- **Instructions:** "Code audit mode. Use Grep and Glob to find accessibility issues in the codebase. Check ARIA, keyboard handlers, semantic HTML, heading hierarchy, alt text, lang attributes, skip-nav, focus management. Write `accessibility-audit.md` and `accessibility-fixes.md` to the output path with actual file paths and line numbers."
+
+### Completion
+
+Display result:
+
+```
+  /gsp:accessibility-audit --code — code audit complete
+  ═══════════════════════════════════════
+
+  {PROJECT_PATH}/review/
+  ├── accessibility-audit.md
+  └── accessibility-fixes.md
+
+  ─────────────────────────────────────
+```
+
+Use `AskUserQuestion`:
+- **Fix issues** — "address the accessibility issues found"
+- **Generate statement** — "create an accessibility statement"
+- **View audit** — "read the code accessibility report"
+- **Done** — "that's all for now"
+
+## Step 5: Statement mode (`--statement`)
+
+Read prior audit results:
+- `{PROJECT_PATH}/critique/accessibility-audit.md`
+- `{PROJECT_PATH}/critique/accessibility-token-audit.md`
+- `{PROJECT_PATH}/review/accessibility-audit.md`
+
+If none exist, tell the user to run an audit first and stop.
+
+### Generate statement
+
+Write `{PROJECT_PATH}/exports/accessibility-statement.md`:
+
+```markdown
+# Accessibility Statement
+
+> Project: {name} | Generated: {DATE}
+
+---
+
+## Conformance Status
+
+**Target:** {level}
+**Status:** {Partially Conformant / Fully Conformant}
+
+This {project description} has been evaluated against {level} standards.
+
+## Scope
+
+{Brief description of what was audited — design, code, or both}
+
+## Known Limitations
+
+{List from audit findings — critical/major issues not yet resolved}
+
+- {Issue}: {brief description} — {planned resolution or workaround}
+
+## Testing Methodology
+
+- Design audit: WCAG 2.2 checklist review of all screens
+- Token audit: Automated contrast ratio verification of all semantic color pairs
+- Code audit: Manual and grep-based review of ARIA, keyboard, semantic HTML
+- Tools used: {list from testing methodology}
+
+## Feedback
+
+If you encounter accessibility barriers, please contact:
+
+- **Email:** [placeholder@example.com]
+- **Response time:** [X business days]
+
+## Assessment Date
+
+Last reviewed: {DATE}
+```
+
+### Completion
+
+Display result and use `AskUserQuestion`:
+- **View statement** — "read the accessibility statement"
+- **Done** — "that's all for now"
+
+## Step 6: Update STATE.md
+
+If within a project and files were written:
+- Read `{PROJECT_PATH}/STATE.md`
+- Note accessibility audit completion in the relevant phase section
+- Do not change phase status — accessibility is a supplementary check
+</process>

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>
@@ -36,22 +37,22 @@ Audit an existing brand. Produce evolution map that guides research, strategy, a
 <process>
 ## Step 1: 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`.
 
 Read `{BRAND_PATH}/BRIEF.md` for aspirational direction.
 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
+
+Read `{BRAND_PATH}/BRIEF.md` — brand assets were already gathered during `/gsp:start`. Extract any logos, colors, guidelines, URLs, or descriptions the user provided.
 
-Use `AskUserQuestion` to prompt for assets:
+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>
@@ -38,9 +40,7 @@ Build the brand's visual identity.
 <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: Validate prerequisites
@@ -77,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,13 +30,15 @@ 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
 
-Scan `.design/branding/` for brand directories. If only one brand exists, use it. If multiple, ask the user which brand to work on.
-
-Set `BRAND_PATH` = `.design/branding/{brand}`
-
+Resolve brand from `.design/branding/` (one → use it, multiple → ask). Set `BRAND_PATH`.
 If BRAND_PATH doesn't exist, tell the user to run `/gsp:start` first.
 
 ## Step 1: Load context
@@ -45,14 +47,11 @@ If BRAND_PATH doesn't exist, tell the user to run `/gsp:start` first.
 
 Read `{BRAND_PATH}/identity/INDEX.md`. If it exists, load all identity chunks + `palettes.json`.
 
-Fallback: read `{BRAND_PATH}/identity/IDENTITY.md` (legacy monolith) + `palettes.json`. Log: "⚠️ Legacy identity format detected — consider re-running /gsp:brand-identity for chunk output."
-
-If neither exists, check if identity phase is complete in brand STATE.md. If not, tell the user to complete brand identity first (run `/gsp:brand-identity`).
+If INDEX.md doesn't exist, check if identity phase is complete in brand STATE.md. If not, tell the user to complete brand identity first (run `/gsp:brand-identity`).
 
 ### Strategy (selective, chunk-first)
 
 Read `{BRAND_PATH}/strategy/INDEX.md`. If it exists, load selective chunks (voice-and-tone.md, brand-platform.md).
-Fallback: read `{BRAND_PATH}/strategy/STRATEGY.md`.
 
 ### Brand context
 
@@ -72,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
 
@@ -109,7 +114,7 @@ Redesign the system from the ground up, informed by what exists.
 ## Step 3: Spawn pattern architect — Pass 1: Foundations
 
 Spawn the `gsp-pattern-architect` agent with:
-- All identity chunks (or IDENTITY.md fallback) + palettes.json
+- All identity chunks + palettes.json
 - The BRIEF.md content
 - The Design System Architect prompt (01)
 - The patterns output template
@@ -127,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:
-
- The Customer ({primary persona name from BRIEF.md}):
- "{would a user recognize this as {brand}? Does the system feel like the brand?}"
+"Before we build the component library:
 
- The Skeptic (internal stakeholder):
- "{challenges system decisions — are the tokens flexible enough? Are the principles actionable?}"
+ {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 Competitor ({top competitor name}):
- "{how does this system compare to industry standards? Any gaps?}"
+Use `AskUserQuestion`:
+- **Build components** — "These foundations are solid, let's go"
+- **Adjust** — "One of these concerns resonates — I want to change something"
 
- 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
 
@@ -214,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

@@ -0,0 +1,148 @@
+---
+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
+- 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
+- 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

@@ -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>
@@ -38,9 +39,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

@@ -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
@@ -40,9 +42,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
@@ -63,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
@@ -45,10 +46,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 +72,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.