get-shit-pretty 0.6.3 → 0.7.0

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-color
-description: Design color systems — palettes, contrast, semantic mapping, dark mode
+description: "Design color systems — palettes, contrast, semantic mapping, dark mode"
 user-invocable: true
 model: sonnet
 allowed-tools:
@@ -15,22 +15,20 @@ allowed-tools:
 You are a GSP color director. You build complete color systems — palette generation, OKLCH scales, WCAG contrast validation, semantic mapping, and dark mode.
 
 This is a standalone composable skill. It works two ways:
-1. **Standalone** — user runs `/gsp-color` directly for palette exploration and contrast checking
+1. **Standalone** — user runs `/gsp-color` directly for palette exploration, contrast checking, or full system design
 2. **As a building block** — the creative-director invokes `/gsp-color --enrich` to add technical precision to creative color choices
-
-Absorbs the capabilities of the current `gsp-palette` (OKLCH generation) and the color audit mode of `gsp-accessibility` (contrast checking).
 </context>
 
 <objective>
-Build a production-ready color system from brand colors or user input.
+Build production-ready color palettes or full color systems from brand colors or user input.
 
-**Input:** Hex colors + brand context, OR `--enrich` mode with existing `color-system.md`
+**Input:** Hex colors, `--preview`, `--enrich`, or interactive
 **Output:** `color-system.md` chunk + `palettes.json` (OKLCH scales)
 **Agent:** None — inline skill, deterministic palette generation + contrast math
 </objective>
 
 <execution_context>
-@${CLAUDE_SKILL_DIR}/../../references/chunk-format.md
+@${CLAUDE_SKILL_DIR}/chunk-format.md
 </execution_context>
 
 <rules>
@@ -40,66 +38,36 @@ Build a production-ready color system from brand colors or user input.
 - Color names must be semantic (primary, secondary, accent, neutral) not literal (red, blue)
 - All foreground/background pairs must report WCAG AA contrast ratios
 - Dark mode mapping must maintain equivalent contrast relationships
+- Foundation chunks follow chunk-format.md format exactly
 </rules>
 
 <process>
-## Step 0: Determine mode
-
-| Input | Mode |
-|-------|------|
-| `/gsp-color --enrich` | Enrich existing color-system.md |
-| `/gsp-color #FF5733 #3366FF` | Generate from hex values |
-| `/gsp-color` | Interactive — explore and build |
-
-## Step 1: Enrich mode (`--enrich`)
-
-Read existing `{BRAND_PATH}/identity/color-system.md`. Extract chosen hex values and rationale.
-
-Read `references/color-composition.md` for domain expertise.
-
-Enrich the file with:
-- OKLCH 11-stop scales via tints.dev API: `https://tints.dev/api/{colorName}/{hexWithout#}`
-- WCAG AA contrast ratios for every semantic foreground/background pair
-- Semantic color mapping (error, success, warning, info)
-- Dark mode color mapping with equivalent contrast
-- Write `palettes.json` alongside color-system.md
-
-Overwrite `color-system.md` with enriched version. Preserve the creative rationale — add technical data around it.
-
-## Step 2: Interactive mode (no args)
-
-One `AskUserQuestion` at a time:
+## Step 0: Parse mode
 
-1. Starting point — use `AskUserQuestion`:
-   - **I have hex values** — "I know my brand colors"
-   - **From a style preset** — "Start from a GSP preset palette"
-   - **Explore** — "Help me find the right palette"
-2. If exploring: ask about mood (warm/cool/neutral), energy (vibrant/muted/earthy), context (tech/health/luxury/etc.)
-3. Propose a palette with primary + secondary + accent + neutral, show hex swatches
-4. Confirm or iterate
+| Input | Mode | Domain |
+|-------|------|--------|
+| `/gsp-color #hex [#hex...] --preview` | Preview scales | palette |
+| `/gsp-color #hex [#hex...]` | Generate from hex | palette |
+| `/gsp-color --enrich` | Enrich existing system | system |
+| `/gsp-color` | Interactive full system | system |
 
-## Step 3: Generate palette system
+## Step 1: Load domain
 
-For each brand color (primary, secondary, accent, neutral):
-1. Call tints.dev API: `WebFetch https://tints.dev/api/{colorName}/{hexWithout#}`
-2. Parse the 11-stop OKLCH scale (50–950)
+Read the domain file for the detected mode:
+- **palette** mode → Read `${CLAUDE_SKILL_DIR}/domains/palette.md`
+- **system** mode → Read `${CLAUDE_SKILL_DIR}/domains/system.md`
 
-Define semantic colors:
-- Map brand colors to semantic roles (primary → CTAs, secondary → supporting, accent → highlights)
-- Define standard semantic colors (error, success, warning, info)
-- Map dark mode equivalents
+For system mode, also read `${CLAUDE_SKILL_DIR}/references/color-composition.md`.
 
-Calculate contrast:
-- Every text/background pair → WCAG AA ratio (4.5:1 normal, 3:1 large)
-- Flag failures with suggested alternatives
+## Step 2: Execute domain framework
 
-## Step 4: Write output
+Follow the loaded domain file's complete workflow — it contains all generation logic, API calls, output formats, and completion steps.
 
-Write `color-system.md` + `palettes.json` to the resolved output path.
+## Step 3: Write output
 
-Target: 100-150 lines for color-system.md.
+Write `color-system.md` + `palettes.json` to the resolved output path (skip if `--preview`).
 
-## Step 5: Completion
+## Step 4: Summary
 
-Display palette summary with contrast status. Offer next steps.
+Display result summary and offer next steps per the domain file's completion section.
 </process>

package/gsp/skills/gsp-color/chunk-format.md

@@ -0,0 +1,79 @@
+# Chunk Format Reference
+
+Standard format for all GSP phase output files. Chunks are the primary output — agents write chunks directly, not monoliths.
+
+## File Format
+
+Every chunk follows this structure:
+
+    # {Section/Component/Screen Name}
+
+    > Phase: {phase} | Brand/Project: {name} | Generated: {DATE}
+
+    ---
+
+    {Content for this chunk}
+
+    ---
+
+    ## Related
+
+    - [{Related chunk name}]({relative-path-to-related-chunk})
+
+## Naming Conventions
+
+- **Singular, kebab-case, lowercase:** "Buttons" → `button.md`, "Date Picker" → `date-picker.md`
+- **Screen files:** `screen-{NN}-{kebab-case-name}.md` (e.g., `screen-01-home.md`)
+
+## INDEX.md Format
+
+Each phase directory gets an INDEX.md manifest:
+
+    # {Phase Name}
+    > Phase: {phase} | Brand/Project: {name} | Generated: {DATE}
+
+    | Chunk | File | ~Lines |
+    |-------|------|--------|
+    | {Section} | [{filename}](./{filename}) | ~{N} |
+
+Lightweight — just a lookup table. No prose.
+
+## Rules
+
+- **Chunks are primary output** — agents write chunks directly to the phase directory
+- **No monoliths** — do not write a single large file then re-chunk it
+- **Size target:** 50-200 lines per chunk
+- **Self-contained:** each chunk must be understandable without loading other chunks
+- **Cross-references:** `## Related` section uses relative paths to related chunks
+- **Idempotent:** re-running a phase regenerates all chunks in that phase directory
+
+## Output Budgets
+
+Context is finite. Every line in a chunk is consumed by downstream agents. Budget accordingly.
+
+### Per-chunk budgets
+
+| Chunk type | Target | Hard max | Notes |
+|-----------|--------|----------|-------|
+| Phase chunk (design, research, etc.) | 50-150 lines | 200 lines | Self-contained, one concept per chunk |
+| INDEX.md | 10-30 lines | 50 lines | Lookup table only, no prose |
+| BUILD-LOG.md | 50-100 lines | 150 lines | Summary + tables, not narrative |
+| Component spec | 30-80 lines | 120 lines | Props, states, behavior — not full implementation |
+| Screen spec | 80-150 lines | 200 lines | Layout, components, interactions, states |
+
+### Per-phase budgets (total across all chunks)
+
+| Phase | Target total | Hard max | Typical chunks |
+|-------|-------------|----------|----------------|
+| Brief | 100-200 lines | 300 lines | 2-4 |
+| Research | 200-400 lines | 600 lines | 5-8 |
+| Design | 300-600 lines | 800 lines | 6-12 |
+| Critique | 100-200 lines | 300 lines | 2-4 |
+| Build log | 50-100 lines | 150 lines | 1 |
+| Review | 100-200 lines | 300 lines | 2-4 |
+
+### Terminal output (inline skills)
+
+- **Diagnostic** (doctor, progress): uncapped — user needs to see it, does not persist in agent context
+- **Greeting/status** (start): 20-40 lines
+- **Phase transitions**: 10-20 lines

package/gsp/skills/{gsp-palette/SKILL.md → gsp-color/domains/palette.md}

@@ -1,85 +1,37 @@
----
-name: gsp-palette
-description: Generate OKLCH color palettes — standalone or as a building block for identity
-user-invocable: true
-model: sonnet
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - AskUserQuestion
-  - WebFetch
----
-<context>
-You are a GSP palette generator. You produce OKLCH 11-stop color scales from input hex colors using the tints.dev API. Downstream agents (creative-director, system-architect, builder) consume the output files.
-
-This is a standalone composable skill. It works two ways:
-1. **Standalone** — user runs `/gsp-palette #FF5733 #3366FF` directly, gets palettes
-2. **As a building block** — identity phase detects existing palette files and reuses them
-</context>
-
-<objective>
-Generate production-ready OKLCH color palettes from hex colors.
-
-**Input:** Hex color(s), optional flags (`--preview`)
-**Output:** `palettes.json` + `color-system.md` foundation chunk in the target directory
-**Agent:** None — deterministic API calls, handled inline
-</objective>
+# Palette Generation
 
-<execution_context>
-@${CLAUDE_SKILL_DIR}/../../references/chunk-format.md
-</execution_context>
+Domain expertise for OKLCH palette generation 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
-- Minimum colors: primary. Secondary and accent are recommended but optional
-- Color names must be semantic (primary, secondary, accent, neutral) not literal (red, blue)
-</rules>
-
-<process>
-## Step 0: Parse invocation
+---
 
-Read the user's input to determine the mode:
+## Modes
 
 | Input | Mode |
 |-------|------|
-| `/gsp-palette #FF5733 #3366FF` | Direct — hex colors from args |
-| `/gsp-palette #FF5733 #3366FF --preview` | Preview — show scales without writing files |
-| `/gsp-palette` | Interactive — ask for colors |
+| `#hex [#hex...]` | Direct — parse hex values, assign roles in order |
+| `#hex [#hex...] --preview` | Preview — show scales without writing files |
 
-## Step 1: Collect colors
+## Color role assignment
 
-### Direct mode (hex args provided)
-
-Parse hex values from the invocation. Assign semantic roles in order:
+Parse hex values from invocation and assign semantic roles in order:
 1. First color → **primary**
 2. Second color → **secondary**
 3. Third color → **accent**
 4. Additional colors → **custom-{n}**
 
-### Interactive mode (no args)
-
-Use `AskUserQuestion` to collect colors:
+Minimum colors: primary. Secondary and accent are recommended but optional.
 
-1. **Primary color** — "What's your primary brand color? (hex code, e.g. #FF5733)"
+Color names must be semantic (primary, secondary, accent, neutral) — not literal (red, blue).
 
-2. **More colors?** — after getting primary:
-   - **Add secondary** — "I have a secondary color"
-   - **Add accent** — "I have an accent color"
-   - **Generate complements** — "suggest secondary/accent from my primary"
-   - **Just primary** — "that's enough, generate from one color"
+## Complement generation
 
-If "generate complements": calculate harmonious colors from the primary:
-- Secondary: rotate hue by 180° (complement)
-- Accent: rotate hue by 30° (analogous)
+When the user has only a primary and wants suggestions:
+- **Secondary:** rotate hue by 180 degrees (complement)
+- **Accent:** rotate hue by 30 degrees (analogous)
 
-Present the generated suggestions and let the user confirm or adjust.
+Present the generated suggestions and let the user confirm or adjust via `AskUserQuestion`.
 
-## Step 2: Generate OKLCH scales via tints.dev API
+## OKLCH scale generation via tints.dev API
 
 For each color, call the tints.dev API:
 
@@ -93,14 +45,16 @@ Where:
 
 The API returns an 11-stop OKLCH scale (50-950) with L, C, H values for each stop.
 
-Parse the response and extract the scale values.
+Every palette gets the full 11-stop scale: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950.
 
-## Step 3: Preview mode (`--preview`)
+Palettes are deterministic — same hex input always produces the same OKLCH scales.
 
-If `--preview`, display the scales without writing files:
+## Preview mode (`--preview`)
+
+Display scales without writing files:
 
 ```
-  /gsp-palette preview
+  /gsp-color preview
   ═══════════════════════════════════════
 
   primary (#FF5733)
@@ -120,14 +74,12 @@ If `--preview`, display the scales without writing files:
     ...
 
   ─────────────────────────────────────
-  Run /gsp-palette #FF5733 #3366FF to write files.
+  Run /gsp-color #FF5733 #3366FF to write files.
 ```
 
 Stop here. Do not write any files.
 
-## Step 4: Resolve output path
-
-Determine where to write the palette output:
+## Output path resolution
 
 ### Within a brand identity
 If a brand context exists (`.design/branding/{brand}/`):
@@ -138,15 +90,13 @@ If a brand context exists (`.design/branding/{brand}/`):
 - Write to `.design/branding/_palette/`
 - Create minimal directory structure
 
-## Step 5: Write palettes.json
+## palettes.json format
 
-If `{OUTPUT_PATH}/palettes.json` already exists, use `AskUserQuestion`: "palettes.json already exists — overwrite with new palette?" with options **Overwrite** and **Cancel**. If cancelled, skip writing palettes.json and proceed to the next step.
-
-Write `{OUTPUT_PATH}/palettes.json` with the full OKLCH scales:
+If `{OUTPUT_PATH}/palettes.json` already exists, use `AskUserQuestion`: "palettes.json already exists — overwrite with new palette?" with options **Overwrite** and **Cancel**. If cancelled, skip writing.
 
 ```json
 {
-  "$description": "OKLCH 11-stop color palettes generated by /gsp-palette",
+  "$description": "OKLCH 11-stop color palettes generated by /gsp-color",
   "$source": "tints.dev",
   "primary": {
     "source": "#FF5733",
@@ -167,9 +117,9 @@ Write `{OUTPUT_PATH}/palettes.json` with the full OKLCH scales:
 }
 ```
 
-## Step 6: Write color-system.md
+## color-system.md format (palette-only)
 
-Write `{OUTPUT_PATH}/color-system.md` as a foundation chunk per `references/chunk-format.md`:
+Write `{OUTPUT_PATH}/color-system.md` as a foundation chunk per chunk-format.md:
 
 ```markdown
 # Color System
@@ -222,16 +172,6 @@ Write `{OUTPUT_PATH}/color-system.md` as a foundation chunk per `references/chun
 | primary-900 (text) | primary-100 | Invert for readability |
 | secondary-500 | secondary-400 | Same shift as primary |
 
-## Semantic Assignments
-
-| Token | Light value | Dark value |
-|-------|-------------|------------|
-| --color-brand | primary-500 | primary-400 |
-| --color-brand-hover | primary-600 | primary-300 |
-| --color-surface | primary-50 | primary-950 |
-| --color-text | primary-900 | primary-50 |
-| --color-accent | accent-500 | accent-400 |
-
 ---
 
 ## Related
@@ -240,12 +180,10 @@ Write `{OUTPUT_PATH}/color-system.md` as a foundation chunk per `references/chun
 - [typography.md](./typography.md)
 ```
 
-## Step 7: Completion output
-
-Display the result:
+## Completion output
 
 ```
-  /gsp-palette — {n} colors scaled
+  /gsp-color — {n} colors scaled
   ═══════════════════════════════════════
 
   {OUTPUT_PATH}/
@@ -257,11 +195,3 @@ Display the result:
 
   ─────────────────────────────────────
 ```
-
-Then use `AskUserQuestion` with routing options:
-
-- **Generate type scale** — "pair these palettes with typography" → route to `/gsp-typescale`
-- **Apply a full style** — "use a style preset for the complete system" → route to `/gsp-style`
-- **Continue to identity** — "use these palettes in the branding diamond" → route to `/gsp-brand-identity`
-- **Done** — "that's all for now"
-</process>

package/gsp/skills/gsp-color/domains/system.md

@@ -0,0 +1,123 @@
+# Color System
+
+Domain expertise for full color system design — creative rationale, contrast validation, semantic mapping, dark mode.
+
+---
+
+## Modes
+
+| Input | Mode |
+|-------|------|
+| `--enrich` | Enrich existing color-system.md with technical precision |
+| *(no args)* | Interactive — explore and build a color system from scratch |
+
+## Enrich mode (`--enrich`)
+
+Read existing `{BRAND_PATH}/identity/color-system.md`. Extract chosen hex values and rationale.
+
+Read `references/color-composition.md` via `${CLAUDE_SKILL_DIR}/references/color-composition.md` for domain expertise on composition strategies.
+
+Enrich the file with:
+- OKLCH 11-stop scales via tints.dev API: `https://www.tints.dev/api/{colorName}/{hexWithoutHash}`
+- WCAG AA contrast ratios for every semantic foreground/background pair
+- Semantic color mapping (error, success, warning, info)
+- Dark mode color mapping with equivalent contrast
+- Write `palettes.json` alongside color-system.md
+
+Overwrite `color-system.md` with enriched version. Preserve the creative rationale — add technical data around it.
+
+## Interactive mode (no args)
+
+One `AskUserQuestion` at a time:
+
+1. **Starting point** — use `AskUserQuestion`:
+   - **I have hex values** — "I know my brand colors"
+   - **From a style preset** — "Start from a GSP preset palette"
+   - **Explore** — "Help me find the right palette"
+2. If exploring: ask about mood (warm/cool/neutral), energy (vibrant/muted/earthy), context (tech/health/luxury/etc.)
+3. Propose a palette with primary + secondary + accent + neutral, show hex swatches
+4. Confirm or iterate
+
+After colors are confirmed, build the full system (contrast, semantics, dark mode).
+
+## WCAG AA contrast validation
+
+Calculate contrast for every text/background pair:
+- Normal text: 4.5:1 minimum
+- Large text (18px+ or 14px+ bold): 3:1 minimum
+- Flag failures with suggested alternatives from the palette scale
+
+Test these combinations:
+- Each semantic color on white (#fff) and black (#000)
+- Primary text on secondary backgrounds and vice versa
+- All foreground/background pairs used in semantic assignments
+
+## Semantic color mapping
+
+Map brand colors to semantic roles:
+- **Primary** → CTAs, primary buttons, links
+- **Secondary** → supporting UI, secondary surfaces
+- **Accent** → highlights, badges, decorative
+
+Define standard semantic colors:
+- **Error** — red-family, distinct from brand palette
+- **Success** — green-family
+- **Warning** — amber/yellow-family
+- **Info** — blue-family (or brand secondary if blue-adjacent)
+
+Each semantic color needs its own 11-stop scale or at minimum light/default/dark stops.
+
+## Dark mode mapping
+
+Maintain equivalent contrast relationships:
+
+| Light mode | Dark mode | Rationale |
+|------------|-----------|-----------|
+| primary-500 (buttons) | primary-400 | Lighter for dark bg contrast |
+| primary-50 (bg tint) | primary-950 | Invert the tint |
+| primary-900 (text) | primary-100 | Invert for readability |
+| secondary-500 | secondary-400 | Same shift as primary |
+| neutral-50 (page bg) | neutral-950 | Full inversion |
+| neutral-900 (body text) | neutral-100 | Full inversion |
+
+## Output structure
+
+Write to the resolved output path:
+
+### color-system.md
+
+Full color system chunk (~100-150 lines) per chunk-format.md including:
+- Source colors table
+- Palette scales (all 11 stops per color)
+- Contrast audit results (pass/fail per pair)
+- Semantic color assignments (light + dark values)
+- Dark mode mapping table
+- Composition strategy recommendation (referencing color-composition.md strategies)
+
+### palettes.json
+
+Full OKLCH scales in structured JSON (same format as palette domain).
+
+### Semantic assignments template
+
+```
+| Token | Light value | Dark value |
+|-------|-------------|------------|
+| --color-brand | primary-500 | primary-400 |
+| --color-brand-hover | primary-600 | primary-300 |
+| --color-surface | primary-50 | primary-950 |
+| --color-text | primary-900 | primary-50 |
+| --color-accent | accent-500 | accent-400 |
+| --color-error | error-500 | error-400 |
+| --color-success | success-500 | success-400 |
+| --color-warning | warning-500 | warning-400 |
+| --color-info | info-500 | info-400 |
+```
+
+## Completion
+
+Display palette summary with contrast status. Offer next steps via `AskUserQuestion`:
+- **Generate type scale** — route to `/gsp-typography`
+- **Apply a full style** — route to `/gsp-style`
+- **Continue to identity** — route to `/gsp-brand-identity`
+- **Done** — "that's all for now"

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

@@ -35,6 +35,11 @@ Scan the codebase and produce five focused design system documents.
 @${CLAUDE_SKILL_DIR}/../../templates/system/CONCERNS.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
+</rules>
+
 <process>
 ## Step 0: Prepare output directory
 

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

@@ -56,11 +56,12 @@ Skill names are left-padded with 4 spaces. Descriptions start at column 27 (4 in
     /gsp-project-review    QA validate implementation against designs
     /gsp-add-reference     add reference material to a project
 
-  ─── Composable ──────────────────────
+  ─── Expertise ───────────────────────
 
+    /gsp-color             color systems — palettes, contrast, semantic mapping, dark mode
+    /gsp-typography        type systems — scale, pairing, fluid type, vertical rhythm
+    /gsp-visuals           visual direction — imagery, 3D, video, textures
     /gsp-accessibility     accessibility audit — contrast, WCAG, code checks
-    /gsp-palette           generate OKLCH color palettes
-    /gsp-typescale         generate mathematical type scales
     /gsp-style             apply a design style preset
 
   ─── Utilities ────────────────────────

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

@@ -30,7 +30,7 @@ Define a complete icon system for a brand or project.
 </objective>
 
 <execution_context>
-@${CLAUDE_SKILL_DIR}/../../references/chunk-format.md
+@${CLAUDE_SKILL_DIR}/chunk-format.md
 </execution_context>
 
 <rules>

package/gsp/skills/gsp-icons/chunk-format.md

@@ -0,0 +1,79 @@
+# Chunk Format Reference
+
+Standard format for all GSP phase output files. Chunks are the primary output — agents write chunks directly, not monoliths.
+
+## File Format
+
+Every chunk follows this structure:
+
+    # {Section/Component/Screen Name}
+
+    > Phase: {phase} | Brand/Project: {name} | Generated: {DATE}
+
+    ---
+
+    {Content for this chunk}
+
+    ---
+
+    ## Related
+
+    - [{Related chunk name}]({relative-path-to-related-chunk})
+
+## Naming Conventions
+
+- **Singular, kebab-case, lowercase:** "Buttons" → `button.md`, "Date Picker" → `date-picker.md`
+- **Screen files:** `screen-{NN}-{kebab-case-name}.md` (e.g., `screen-01-home.md`)
+
+## INDEX.md Format
+
+Each phase directory gets an INDEX.md manifest:
+
+    # {Phase Name}
+    > Phase: {phase} | Brand/Project: {name} | Generated: {DATE}
+
+    | Chunk | File | ~Lines |
+    |-------|------|--------|
+    | {Section} | [{filename}](./{filename}) | ~{N} |
+
+Lightweight — just a lookup table. No prose.
+
+## Rules
+
+- **Chunks are primary output** — agents write chunks directly to the phase directory
+- **No monoliths** — do not write a single large file then re-chunk it
+- **Size target:** 50-200 lines per chunk
+- **Self-contained:** each chunk must be understandable without loading other chunks
+- **Cross-references:** `## Related` section uses relative paths to related chunks
+- **Idempotent:** re-running a phase regenerates all chunks in that phase directory
+
+## Output Budgets
+
+Context is finite. Every line in a chunk is consumed by downstream agents. Budget accordingly.
+
+### Per-chunk budgets
+
+| Chunk type | Target | Hard max | Notes |
+|-----------|--------|----------|-------|
+| Phase chunk (design, research, etc.) | 50-150 lines | 200 lines | Self-contained, one concept per chunk |
+| INDEX.md | 10-30 lines | 50 lines | Lookup table only, no prose |
+| BUILD-LOG.md | 50-100 lines | 150 lines | Summary + tables, not narrative |
+| Component spec | 30-80 lines | 120 lines | Props, states, behavior — not full implementation |
+| Screen spec | 80-150 lines | 200 lines | Layout, components, interactions, states |
+
+### Per-phase budgets (total across all chunks)
+
+| Phase | Target total | Hard max | Typical chunks |
+|-------|-------------|----------|----------------|
+| Brief | 100-200 lines | 300 lines | 2-4 |
+| Research | 200-400 lines | 600 lines | 5-8 |
+| Design | 300-600 lines | 800 lines | 6-12 |
+| Critique | 100-200 lines | 300 lines | 2-4 |
+| Build log | 50-100 lines | 150 lines | 1 |
+| Review | 100-200 lines | 300 lines | 2-4 |
+
+### Terminal output (inline skills)
+
+- **Diagnostic** (doctor, progress): uncapped — user needs to see it, does not persist in agent context
+- **Greeting/status** (start): 20-40 lines
+- **Phase transitions**: 10-20 lines

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

@@ -93,5 +93,5 @@ Update `{PROJECT_PATH}/STATE.md`:
 
 ## Step 4: Phase transition output
 
-Render phase transition (see `references/phase-transitions.md`). This is the final phase.
+Invoke `/gsp-phase-transition` with phase `launch` and output directory `{PROJECT_PATH}/launch/`.
 </process>