get-shit-pretty 0.7.4 → 0.8.3

package/gsp/skills/gsp-brand-guidelines/token-mapping.md

@@ -1,329 +1,26 @@
-# Token Mapping Reference
+# Token Mapping → bin/theme-css.js
 
-Deterministic mapping from GSP style preset `.yml` tokens to target CSS variable systems. The builder reads the `.yml` and generates the right output for the detected stack — no separate `tokens.json` or `token-mapping.md` needed.
+> **Superseded in v0.8.0.** The static mapping table has been replaced by a deterministic script.
 
-## Source: `.yml` Token Structure
+GSP presets use shadcn/ui-native token names directly. The `.yml` token keys match shadcn CSS variable names 1:1 — no translation layer is needed.
 
-Every preset (and every brand `.yml`) has this structure:
+## Generating CSS from a preset
 
-```yaml
-tokens:
-  color:
-    primary: "#hex"        # Brand primary
-    secondary: "#hex"      # Brand secondary
-    accent: "#hex"         # Brand accent
-    background: "#hex"     # Page background
-    surface: "#hex"        # Card/panel fill
-    on-primary: "#hex"     # Text on primary
-    on-background: "#hex"  # Text on background
-    error: "#hex"
-    success: "#hex"
-    warning: "#hex"
-    info: "#hex"
-    muted: "#hex"          # Subtle text, borders (optional)
-
-  typography:
-    font-family-primary: "stack"
-    font-family-mono: "stack"
-    font-family-display: "stack"     # optional
-    font-family-secondary: "stack"   # optional
-    font-weight-heading: N
-    font-weight-body: N
-    font-size-base: "Npx"
-    line-height-base: N
-
-  shape:
-    border-radius-sm: "Npx"
-    border-radius-md: "Npx"
-    border-radius-lg: "Npx"
-    border-width: "Npx"
-    border-color: "#hex"
-
-  elevation:
-    shadow-sm: "css-shadow"
-    shadow-md: "css-shadow"
-    shadow-lg: "css-shadow"
-    shadow-xl: "css-shadow"
-
-  spacing:
-    base: N
-    scale: [N, N, ...]
-
-  motion:
-    duration-fast: "Nms"
-    duration-normal: "Nms"
-    easing: "css-easing"
-
-dark_mode:
-  color:
-    background: "#hex"
-    surface: "#hex"
-    on-background: "#hex"
-    border-color: "#hex"   # optional
-    muted: "#hex"          # optional
-```
-
----
-
-## Target: shadcn/ui
-
-shadcn uses HSL CSS variables in `:root` and `.dark`. The mapping is deterministic — every `.yml` token has exactly one shadcn variable.
-
-### Color mapping
-
-| `.yml` token | shadcn CSS variable | Notes |
-|---|---|---|
-| `color.background` | `--background` | Page background |
-| `color.on-background` | `--foreground` | Primary text |
-| `color.surface` | `--card` | Card background |
-| `color.on-background` | `--card-foreground` | Card text (same as foreground) |
-| `color.surface` | `--popover` | Popover bg (same as card) |
-| `color.on-background` | `--popover-foreground` | Popover text |
-| `color.primary` | `--primary` | Primary actions |
-| `color.on-primary` | `--primary-foreground` | Text on primary |
-| `color.secondary` | `--secondary` | Secondary actions |
-| `color.on-primary` | `--secondary-foreground` | Text on secondary (derive from contrast) |
-| `color.muted` | `--muted` | Muted backgrounds |
-| `color.muted` | `--muted-foreground` | Muted text (use muted or derive darker) |
-| `color.accent` | `--accent` | Accent highlights |
-| `color.on-primary` | `--accent-foreground` | Text on accent (derive from contrast) |
-| `color.error` | `--destructive` | Destructive actions |
-| `color.on-primary` | `--destructive-foreground` | Text on destructive |
-| `shape.border-color` | `--border` | Default borders |
-| `shape.border-color` | `--input` | Input borders |
-| `color.primary` | `--ring` | Focus ring |
-| `color.surface` | `--sidebar-background` | Sidebar bg |
-| `color.on-background` | `--sidebar-foreground` | Sidebar text |
-| `color.primary` | `--sidebar-primary` | Sidebar active |
-| `color.on-primary` | `--sidebar-primary-foreground` | Sidebar active text |
-| `color.accent` | `--sidebar-accent` | Sidebar accent |
-| `color.on-background` | `--sidebar-accent-foreground` | Sidebar accent text |
-| `shape.border-color` | `--sidebar-border` | Sidebar borders |
-| `color.primary` | `--sidebar-ring` | Sidebar focus ring |
-| | `--chart-1` through `--chart-5` | Derive from primary, secondary, accent, info, success |
-
-### Shape mapping
-
-| `.yml` token | shadcn CSS variable |
-|---|---|
-| `shape.border-radius-lg` | `--radius` |
-
-shadcn derives `--radius` down: `calc(var(--radius) - 2px)` for md, `calc(var(--radius) - 4px)` for sm.
-
-### Typography
-
-shadcn doesn't use CSS variables for fonts — set in `tailwind.config` `fontFamily` extend:
-
-```js
-fontFamily: {
-  sans: [/* from typography.font-family-primary */],
-  mono: [/* from typography.font-family-mono */],
-}
-```
-
-### Dark mode
-
-| `.yml` dark_mode token | shadcn CSS variable (`.dark` scope) |
-|---|---|
-| `dark_mode.color.background` | `--background` |
-| `dark_mode.color.on-background` | `--foreground` |
-| `dark_mode.color.surface` | `--card`, `--popover` |
-| `dark_mode.color.border-color` | `--border`, `--input` |
-| `dark_mode.color.muted` | `--muted`, `--muted-foreground` |
-
-Tokens not listed in `dark_mode` inherit their light-mode value.
-
-### Color format conversion
-
-shadcn expects HSL channel values (no `hsl()` wrapper): `210 40% 98%`
-
-**Conversion:** hex → HSL → extract H S% L% as space-separated string.
-
-```
-#1E40AF → hsl(221, 72%, 40%) → "221 72% 40%"
+```bash
+node bin/theme-css.js gsp/skills/gsp-style/styles/professional.yml --stdout
 ```
 
-### Complete output example
-
-Given `professional.yml`:
-
-```css
-@layer base {
-  :root {
-    --background: 0 0% 100%;
-    --foreground: 222 47% 11%;
-    --card: 210 40% 98%;
-    --card-foreground: 222 47% 11%;
-    --popover: 210 40% 98%;
-    --popover-foreground: 222 47% 11%;
-    --primary: 221 72% 40%;
-    --primary-foreground: 0 0% 100%;
-    --secondary: 215 16% 47%;
-    --secondary-foreground: 0 0% 100%;
-    --muted: 213 27% 84%;
-    --muted-foreground: 215 16% 47%;
-    --accent: 199 89% 48%;
-    --accent-foreground: 0 0% 100%;
-    --destructive: 0 72% 51%;
-    --destructive-foreground: 0 0% 100%;
-    --border: 214 32% 91%;
-    --input: 214 32% 91%;
-    --ring: 221 72% 40%;
-    --radius: 0.75rem;
-    --chart-1: 221 72% 40%;
-    --chart-2: 215 16% 47%;
-    --chart-3: 199 89% 48%;
-    --chart-4: 217 91% 60%;
-    --chart-5: 142 71% 45%;
-  }
-
-  .dark {
-    --background: 222 47% 11%;
-    --foreground: 210 40% 96%;
-    --card: 217 33% 17%;
-    --card-foreground: 210 40% 96%;
-    --popover: 217 33% 17%;
-    --popover-foreground: 210 40% 96%;
-    --border: 217 19% 27%;
-    --input: 217 19% 27%;
-    --muted: 215 20% 65%;
-    --muted-foreground: 215 20% 65%;
-  }
-}
-```
-
----
-
-## Target: Tailwind (no component library)
-
-For codebases using Tailwind without shadcn, map directly to `tailwind.config` `extend`:
-
-```js
-theme: {
-  extend: {
-    colors: {
-      primary: "var(--color-primary)",
-      secondary: "var(--color-secondary)",
-      accent: "var(--color-accent)",
-      background: "var(--color-background)",
-      surface: "var(--color-surface)",
-      foreground: "var(--color-foreground)",
-      muted: "var(--color-muted)",
-      error: "var(--color-error)",
-      success: "var(--color-success)",
-      warning: "var(--color-warning)",
-    },
-    fontFamily: {
-      sans: [/* typography.font-family-primary */],
-      mono: [/* typography.font-family-mono */],
-    },
-    borderRadius: {
-      sm: "var(--radius-sm)",
-      md: "var(--radius-md)",
-      lg: "var(--radius-lg)",
-    },
-    boxShadow: {
-      sm: "var(--shadow-sm)",
-      md: "var(--shadow-md)",
-      lg: "var(--shadow-lg)",
-      xl: "var(--shadow-xl)",
-    },
-  }
-}
-```
-
-CSS variables use hex directly (no HSL conversion needed):
-
-```css
-:root {
-  --color-primary: #1E40AF;
-  --color-secondary: #475569;
-  --color-background: #FFFFFF;
-  --color-surface: #F8FAFC;
-  --color-foreground: #0F172A;
-  --color-muted: #94A3B8;
-  --radius-sm: 6px;
-  --radius-md: 8px;
-  --radius-lg: 12px;
-  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
-  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
-}
-```
-
----
-
-## Target: Vanilla CSS
-
-For non-Tailwind codebases, generate a CSS custom property system with semantic class recipes:
-
-```css
-:root {
-  /* Brand */
-  --color-primary: #1E40AF;
-  --color-secondary: #475569;
-  --color-accent: #0EA5E9;
-  --color-bg: #FFFFFF;
-  --color-surface: #F8FAFC;
-  --color-text: #0F172A;
-  --color-muted: #94A3B8;
-  --color-border: #E2E8F0;
-
-  /* Semantic */
-  --color-error: #DC2626;
-  --color-success: #16A34A;
-  --color-warning: #D97706;
-
-  /* Shape */
-  --radius-sm: 6px;
-  --radius-md: 8px;
-  --radius-lg: 12px;
-  --border-width: 1px;
-
-  /* Elevation */
-  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
-  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
-
-  /* Spacing */
-  --space-1: 4px;
-  --space-2: 8px;
-  --space-3: 12px;
-  --space-4: 16px;
-  --space-6: 24px;
-  --space-8: 32px;
-  --space-12: 48px;
-  --space-16: 64px;
-
-  /* Motion */
-  --duration-fast: 150ms;
-  --duration-normal: 250ms;
-  --easing: cubic-bezier(0.4, 0, 0.2, 1);
-
-  /* Typography */
-  --font-sans: Inter, system-ui, sans-serif;
-  --font-mono: SF Mono, Menlo, monospace;
-  --font-weight-heading: 600;
-  --font-weight-body: 400;
-  --font-size-base: 16px;
-  --line-height-base: 1.6;
-}
-```
-
----
-
-## Layered resolution
-
-The builder resolves tokens in this order (last wins):
+Output is `:root { }` + `.dark { }` blocks ready to paste into `globals.css`.
 
-1. **Preset `.yml`** — base tokens from the style preset (e.g., `professional.yml`)
-2. **Brand `.yml`** — overrides from branding process (e.g., `acme.yml` with `style_base: professional`)
-3. **Dark mode** — `dark_mode.color.*` overrides for `.dark` scope
+## How it works
 
-If only a preset exists (quick project), step 2 is skipped. The builder generates CSS from whatever `.yml` it receives.
+- Hex `#RRGGBB` values → converted to OKLCH (full color math: sRGB → linear → XYZ → OKLab → OKLCh)
+- Values containing `oklch(` → passed through as-is (handles alpha variants)
+- All other values (font stacks, shadows, etc.) → passed through verbatim
+- `--radius` derived from `shape.border-radius-lg`
+- `--chart-1` through `--chart-5` derived from palette colors
+- Sidebar vars written from explicit `color.sidebar-*` tokens in the `.yml`
 
-## When to generate extended files
+## Token structure
 
-| Scenario | Files produced |
-|----------|---------------|
-| Quick project (`/gsp-style`) | Preset `.yml` (base) → CSS vars generated at build time |
-| Full branding (customized) | Brand `.yml` (inherits preset) + `STYLE.md` |
-| Full branding (unchanged from preset) | Only `STYLE.md` (brand `.yml` not needed if identical to preset) |
+See `${CLAUDE_SKILL_DIR}/../gsp-style/style-preset-schema.md` for the full `.yml` schema — all shadcn variables are first-class token keys.

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-brand-identity
-description: Create your visual identity — logo, color, typography (creative phase — benefits from capable models)
+description: Create visual identity — logo, color, typography (creative phase — benefits from capable models) — use when: design the logo, pick colors, choose fonts, create the visual identity
 user-invocable: true
 allowed-tools:
   - Read

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-brand-refine
-description: Targeted brand adjustments mid-project — tweak colors, typography, or spacing without re-running the full branding diamond
+description: Adjust brand mid-project — use when: tweak the colors, change the font, adjust spacing, the brand feels off, refine the brand
 user-invocable: true
 allowed-tools:
   - Read
@@ -82,14 +82,13 @@ Show a clear before/after for each affected token:
 
   ─── Proposed Changes ─────────────────
 
-  color.brand.accent
+  color.accent
     before: #B8860B
     after:  #E8A317
     change: increased chroma
 
   Cascade:
-    color.semantic.link        → #E8A317
-    color.semantic.focus-ring  → #E8A317
+    color.ring  → #E8A317 (shares accent as focus ring)
 
   Contrast: accent on white 3.2:1 → 2.8:1 ⚠️ below AA
             accent on dark  8.4:1 → 9.2:1 ✓
@@ -133,8 +132,8 @@ Append to `{BRAND_PATH}/REFINE-LOG.md`:
 
 | Token | Before | After |
 |-------|--------|-------|
-| color.brand.accent | #B8860B | #E8A317 |
-| color.semantic.link | #B8860B | #E8A317 |
+| color.accent | #B8860B | #E8A317 |
+| color.ring | #B8860B | #E8A317 |
 ```
 
 Display summary:

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-brand-research
-description: Research your market and competitors
+description: Research market and competitors — use when: research competitors, who else is doing this, market analysis, what do competitors look like
 user-invocable: true
 allowed-tools:
   - Read

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-brand-strategy
-description: Define positioning, voice, and messaging (creative phase — benefits from capable models)
+description: Define positioning, voice, and messaging (creative phase — benefits from capable models) — use when: define our positioning, brand strategy, what's our voice, how do we talk to customers
 user-invocable: true
 allowed-tools:
   - Read

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-design-system
-description: Scan and document the existing design system state
+description: Scan and document the existing design system — use when: scan the codebase, document what components exist, what's already built, inventory the design system
 user-invocable: true
 allowed-tools:
   - Read

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-doctor
-description: Check project health
+description: Check project health — use when: something's broken, check the project, is everything set up right, health check, what's the status of my GSP setup
 user-invocable: true
 allowed-tools:
   - Read
@@ -87,6 +87,9 @@ Check each exists:
 - All present → PASS
 - Core files missing → FAIL: list which are missing, suggest `/gsp-start`
 
+**Monorepo app_path check:**
+- If `repo_type` is `monorepo` (in config.json) and `app_path` is empty → WARN: "Project has no `app_path` set. Run `/gsp-project-brief` to assign a target app."
+
 **Design system check:**
 - If `.design/system/` directory exists, verify at least `STACK.md` is present → PASS
 - If `.design/system/` is missing and codebase is not greenfield → WARN: "Design system scan missing. Run `/gsp-design-system` to scan."
@@ -242,12 +245,12 @@ Glob for all SKILL.md files in the skills directory (`{runtime-dir}/skills/*/SKI
 **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`"
+- Missing siblings → FAIL: "Skill {name} references {path} but it's missing. Re-run the installer: `pnpm dlx get-shit-pretty` (or `bunx get-shit-pretty`)"
 
 **Check I3: Bundle directories accessible**
 Check that the runtime bundle directories exist (`{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`"
+- Missing → FAIL: "Bundle directory {dir} missing. Re-run the installer: `pnpm dlx get-shit-pretty` (or `bunx get-shit-pretty`)"
 
 **Check I4: VERSION file present**
 Check `{runtime-dir}/VERSION` exists and contains a valid semver string.
@@ -259,9 +262,47 @@ Check `{runtime-dir}/VERSION` exists and contains a valid semver string.
 Check if `~/.claude/skills/` contains `gsp-*` directories when running from a local install. These cause duplicates between global and local.
 - Run: `ls ~/.claude/skills/ | grep '^gsp-'`
 - No matches → PASS
-- Matches found → FAIL: "Found {N} stale GSP skills in ~/.claude/skills/. Fix: run `npx get-shit-pretty --claude --local` to reinstall (the installer cleans stale globals automatically), or manually remove: `rm -rf ~/.claude/skills/gsp-*`"
+- Matches found → FAIL: "Found {N} stale GSP skills in ~/.claude/skills/. Fix: run `pnpm dlx get-shit-pretty --claude --local` (or `bunx get-shit-pretty --claude --local`) to reinstall (the installer cleans stale globals automatically), or manually remove: `rm -rf ~/.claude/skills/gsp-*`"
+
+### Stack Compliance Checks (shadcn targets)
+
+Only run these checks when `.design/system/STACK.md` exists and at least one project has `implementation_target: shadcn`.
+
+> **Monorepo note:** For monorepos, each project's S-checks run in its declared `app_path`. Read `config.json` → `preferences.app_path` before running commands. If `app_path` is empty, run in repo root.
+
+**Check S1: Alias drift**
+
+Read `config.json` → `preferences.app_path`. Set `APP_PATH` (default `.` if empty).
+
+Run `cd {APP_PATH} && npx shadcn@latest info --json` and extract `aliases.components`. Compare to `## Key Paths → Components` in STACK.md.
+
+If mismatch → FAIL: "shadcn alias drift — STACK.md declares `{declared}` but live config has `{live}`. Imports will break. Fix by updating `components.json` or `STACK.md`."
+
+**Check S2: Tailwind version drift**
+
+Run `cd {APP_PATH} && node -e "console.log(require('tailwindcss/package.json').version)"`. Compare major version to `## Tech Stack → Styling` in STACK.md.
+
+If major version differs → FAIL: "Tailwind version drift — STACK.md declares `{declared}` but `{live}` is installed. Run `/gsp-scaffold` to realign or update STACK.md."
+
+**Check S3: Icon library drift**
+
+Read `components.json` → `iconLibrary`. Compare to icon library recorded in STACK.md (if present).
+
+If mismatch → WARN: "Icon library drift — STACK.md declares `{declared}` but `components.json` says `{live}`. Agents may import from the wrong package."
+
+**Check S4: Token presence in globals.css**
+
+Find the global CSS file (from `cd {APP_PATH} && npx shadcn@latest info --json` → `tailwindCssFile`, or glob for `globals.css` inside `APP_PATH`). Check it contains `--background`, `--foreground`, `--primary` CSS custom properties.
+
+If missing → WARN: "CSS custom properties not found in `{file}`. Token integration may be incomplete. Run `/gsp-project-build` foundations phase to regenerate."
+
+**Check S5: Tailwind v4 source scoping (if Tailwind v4)**
+
+If Tailwind v4 detected, check `globals.css` for `@import "tailwindcss"`. If present without `source(...)` modifier, and the repo contains non-source directories with Tailwind class names (like `.design/`) → WARN: "Tailwind v4 source not scoped. Add `source(\"../\")` to avoid scanning `.design/` spec files."
+
+All S checks pass → single PASS line: "S1-S5. Stack compliance .......... PASS"
+
 
-### Cross-Instance Checks
 
 **Check X1: Multiple projects, same brand**
 If multiple projects reference the same brand, and brand has changed since any project consumed it → WARN with list of affected projects.
@@ -314,7 +355,14 @@ Overall Health: {SCORE}/100 {emoji}
   ✅ I4. VERSION file ............ PASS
   ✅ I5. No duplicate skills ..... PASS
 
-─── Cross-Instance ────────────────────
+  ─── Stack Compliance (shadcn) ────────
+  ✅ S1. Alias ....................... PASS
+  ✅ S2. Tailwind version ........... PASS
+  ✅ S3. Icon library ............... PASS
+  ✅ S4. CSS custom properties ....... PASS
+  ✅ S5. Source scoping .............. PASS
+
+  ─── Cross-Instance ────────────────────
   ✅ X1. Brand Consistency ...... PASS
 
 ─── Issues Found ──────────────────────

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-progress
-description: How pretty are we?
+description: Show pipeline progress dashboard — use when: where are we, what's done, show progress, how far along, what phase are we on
 user-invocable: true
 allowed-tools:
   - Read

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-project-brief
-description: Scope what you're building
+description: Scope a feature or flow — use when: scope this, define what we're building, plan the project, what should we build, write a brief
 user-invocable: true
 allowed-tools:
   - Read
@@ -31,6 +31,8 @@ Scope the project and plan adaptations from the brand system.
 <process>
 ## Step 0: Resolve project and brand
 
+If `.design/projects/` does not exist: output "No GSP project found. Run `/gsp-start` to begin." and stop.
+
 Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
 Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`. If brand.ref doesn't exist, tell the user to run `/gsp-start`.
@@ -49,16 +51,41 @@ Also read the brand `.yml` preset from `{BRAND_PATH}/patterns/`.
 
 Read:
 - `{PROJECT_PATH}/BRIEF.md` — what we're building, platforms, tech stack
-- `{PROJECT_PATH}/config.json` — get `implementation_target`, `design_scope`, `codebase_type`
+- `{PROJECT_PATH}/config.json` — get `implementation_target`, `design_scope`, `codebase_type`, `app_path`, `repo_type`
+
+After reading config, check if `app_path` is empty. If empty AND (`repo_type` is `monorepo` OR multiple `package.json` files are found at `apps/*/package.json` or `packages/*/package.json`), set flag `NEEDS_APP_SELECTION = true`.
 
 ### Codebase context
 
 Read `.design/system/STACK.md` and `.design/system/COMPONENTS.md` (if exist) — existing tech stack, components, architecture.
 
+**Stack inheritance (existing codebases):** If `STACK.md` exists and the project `config.json` has empty or generic values for `tech_stack`, `implementation_target`, or `codebase_type`, inherit them from `STACK.md` directly — do not ask the user questions the stack already answers. Update `config.json` with the inherited values before proceeding.
+
+The global stack is the compliance baseline. Every project in this workspace must target it. If the user's brief describes a different stack than what `STACK.md` declares (e.g., "I want to use Radix directly" when `STACK.md` says `shadcn/ui`), surface the conflict: "⚠️ Your brief mentions {X}, but the workspace stack is {Y} per STACK.md. Proceed with the workspace stack, or update STACK.md first?"
+
 Read `.design/CHANGELOG.md` — quick history of what prior projects built.
 For projects with overlapping scope, read their `codebase/MANIFEST.md` for detail.
 Glob `.design/projects/*/STATE.md` — detect active sibling projects.
 
+## Step 1.3: App targeting
+
+Run when `NEEDS_APP_SELECTION = true`.
+
+1. Glob for `apps/*/package.json` and `packages/*/package.json` to find all app packages.
+2. Read each package.json to extract `name` and the primary framework dependency (Next.js, Vite, React Native, etc.).
+3. Build an app list, e.g.:
+   ```
+   apps/web        → my-app-web     (Next.js)
+   apps/mobile     → my-app-mobile  (Expo / React Native)
+   packages/ui     → my-app-ui      (Vite)
+   ```
+4. Use `AskUserQuestion`: "Which app does this project target?" with one option per detected app (showing path + framework) plus **Whole repo (no specific app)**.
+5. Based on the user's choice:
+   - If an app was selected: set `app_path` to the chosen path (e.g. `apps/web`) and `repo_type` to `monorepo`
+   - If "Whole repo" was selected: set `app_path` to `""` and `repo_type` to `monorepo`
+6. Write the updated `app_path` and `repo_type` back to `{PROJECT_PATH}/config.json`.
+7. Derive `APP_NAME` = last segment of `app_path` (e.g. `apps/web` → `web`, empty → `root`). Note that the per-app stack file will live at `.design/system/stacks/{APP_NAME}.md`.
+
 ## Step 1.5: Scope check
 
 **If `design_scope` is `tokens`:**
@@ -69,10 +96,10 @@ Glob `.design/projects/*/STATE.md` — detect active sibling projects.
 
 ## Step 1.7: Issue framing
 
-Suggest to the user:
-"Consider framing this project as a bounded issue (or set of issues) and a PR. Smaller scope = higher quality. What's the tightest version of this that ships?"
-
-If the project scope feels large, suggest breaking it into multiple bounded issues — each one a focused deliverable that can be reviewed independently.
+Ask the user (via `AskUserQuestion`): "Is this project linked to a GitHub issue?"
+- **Yes — paste the issue URL** → read the issue number from the URL, write `git.issue` to `{PROJECT_PATH}/config.json` and populate the `| Issue |` row in STATE.md. Also read the issue title/body via `gh issue view {number} --json title,body,labels` and use that content to pre-populate scope context (saves the user from re-describing what the issue already states).
+- **No — describe it** → continue with manual brief as before
+- **Skip** → continue without issue link
 
 ## Step 2: Scope the project
 
@@ -157,6 +184,13 @@ Update `{PROJECT_PATH}/STATE.md`:
 - Set Phase 1 (Brief) status to `complete`
 - Record completion date
 
+Write/update `.design/CLAUDE.md` — register the project as started. If the file doesn't exist, read the template from `${CLAUDE_SKILL_DIR}/../../templates/design-claude.md` first. Append under `## Projects`:
+
+```markdown
+### {project-name} · in progress · {DATE}
+brand: {brand-name} · next: gsp-project-research · .design/projects/{project-name}/
+```
+
 ## Step 5: Phase transition output
 
 Invoke `/gsp-phase-transition` with phase `brief` and output directory `{PROJECT_PATH}/brief/`.