6 files changed, 246 insertions(+), 71 deletions(-)

M CHANGELOG.md
M README.md
M VERSION
M design-html/SKILL.md
M design-html/SKILL.md.tmpl
M docs/skills.md

@@ 1,5 1,14 @@
 # Changelog
 
+## [0.15.1.0] - 2026-04-01 — Design Without Shotgun
+
+You can now run `/design-html` without having to run `/design-shotgun` first. The skill detects what design context exists (CEO plans, design review artifacts, approved mockups) and asks how you want to proceed. Start from a plan, a description, or a provided PNG, not just an approved mockup.
+
+### Changed
+
+- **`/design-html` works from any starting point.** Three routing modes: (A) approved mockup from /design-shotgun, (B) CEO plan and/or design variants without formal approval, (C) clean slate with just a description. Each mode asks the right questions and proceeds accordingly.
+- **AskUserQuestion for missing context.** Instead of blocking with "no approved design found," the skill now offers choices: run the planning skills first, provide a PNG, or just describe what you want and design live.
+
 ## [0.15.0.0] - 2026-04-01 — Session Intelligence
 
 Your AI sessions now remember what happened. Plans, reviews, checkpoints, and health scores survive context compaction and compound across sessions. Every skill writes a timeline event, and the preamble reads recent artifacts on startup so the agent knows where you left off.

@@ 165,7 165,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
 | `/investigate` | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. |
 | `/design-review` | **Designer Who Codes** | Same audit as /plan-design-review, then fixes what it finds. Atomic commits, before/after screenshots. |
 | `/design-shotgun` | **Design Explorer** | Generate multiple AI design variants, open a comparison board in your browser, and iterate until you approve a direction. Taste memory biases toward your preferences. |
-| `/design-html` | **Design Engineer** | Takes an approved mockup from `/design-shotgun` and generates production-quality HTML with Pretext for computed text layout. Text reflows on resize, heights adjust to content. Smart API routing picks the right Pretext patterns per design type. Framework detection for React/Svelte/Vue. |
+| `/design-html` | **Design Engineer** | Generates production-quality HTML with Pretext for computed text layout. Works with approved mockups, CEO plans, design reviews, or from scratch. Text reflows on resize, heights adjust to content. Smart API routing picks the right Pretext patterns per design type. Framework detection for React/Svelte/Vue. |
 | `/qa` | **QA Lead** | Test your app, find bugs, fix them with atomic commits, re-verify. Auto-generates regression tests for every fix. |
 | `/qa-only` | **QA Reporter** | Same methodology as /qa but report only. Pure bug report without code changes. |
 | `/cso` | **Chief Security Officer** | OWASP Top 10 + STRIDE threat model. Zero-noise: 17 false positive exclusions, 8/10+ confidence gate, independent finding verification. Each finding includes a concrete exploit scenario. |

@@ 1,1 1,1 @@
-0.15.0.0
+0.15.1.0

@@ 3,13 3,14 @@ name: design-html
 preamble-tier: 2
 version: 1.0.0
 description: |
-  Design finalization: takes an approved AI mockup from /design-shotgun and
-  generates production-quality Pretext-native HTML/CSS. Text actually reflows,
-  heights are computed, layouts are dynamic. 30KB overhead, zero deps.
-  Smart API routing: picks the right Pretext patterns for each design type.
-  Use when: "finalize this design", "turn this mockup into HTML", "implement
-  this design", or after /design-shotgun approves a direction.
-  Proactively suggest when user has approved a design in /design-shotgun. (gstack)
+  Design finalization: generates production-quality Pretext-native HTML/CSS.
+  Works with approved mockups from /design-shotgun, CEO plans from /plan-ceo-review,
+  design review context from /plan-design-review, or from scratch with a user
+  description. Text actually reflows, heights are computed, layouts are dynamic.
+  30KB overhead, zero deps. Smart API routing: picks the right Pretext patterns
+  for each design type. Use when: "finalize this design", "turn this into HTML",
+  "build me a page", "implement this design", or after any planning skill.
+  Proactively suggest when user has approved a design or has a plan ready. (gstack)
 allowed-tools:
   - Bash
   - Read


@@ 556,37 557,97 @@ If `NEEDS_SETUP`:
 eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
 ```
 
-1. Find the most recent `approved.json`:
+Detect what design context exists for this project. Run all four checks:
+
 ```bash
 setopt +o nomatch 2>/dev/null || true
-ls -t ~/.gstack/projects/$SLUG/designs/*/approved.json 2>/dev/null | head -1
+_CEO=$(ls -t ~/.gstack/projects/$SLUG/ceo-plans/*.md 2>/dev/null | head -1)
+[ -n "$_CEO" ] && echo "CEO_PLAN: $_CEO" || echo "NO_CEO_PLAN"
 ```
 
-2. If found, read it. Extract: approved variant PNG path, user feedback, screen name.
+```bash
+setopt +o nomatch 2>/dev/null || true
+_APPROVED=$(ls -t ~/.gstack/projects/$SLUG/designs/*/approved.json 2>/dev/null | head -1)
+[ -n "$_APPROVED" ] && echo "APPROVED: $_APPROVED" || echo "NO_APPROVED"
+```
 
-3. Read `DESIGN.md` if it exists in the repo root. These tokens take priority for
-   system-level values (fonts, brand colors, spacing scale).
+```bash
+setopt +o nomatch 2>/dev/null || true
+_VARIANTS=$(ls -t ~/.gstack/projects/$SLUG/designs/*/variant-*.png 2>/dev/null | head -1)
+[ -n "$_VARIANTS" ] && echo "VARIANTS: $_VARIANTS" || echo "NO_VARIANTS"
+```
 
-4. **Evolve mode:** Check for prior output:
 ```bash
 setopt +o nomatch 2>/dev/null || true
-ls -t ~/.gstack/projects/$SLUG/designs/*/finalized.html 2>/dev/null | head -1
+_FINALIZED=$(ls -t ~/.gstack/projects/$SLUG/designs/*/finalized.html 2>/dev/null | head -1)
+[ -n "$_FINALIZED" ] && echo "FINALIZED: $_FINALIZED" || echo "NO_FINALIZED"
+[ -f DESIGN.md ] && echo "DESIGN_MD: exists" || echo "NO_DESIGN_MD"
 ```
-If a prior `finalized.html` exists, use AskUserQuestion:
+
+Now route based on what was found. Check these cases in order:
+
+### Case A: approved.json exists (design-shotgun ran)
+
+If `APPROVED` was found, read it. Extract: approved variant PNG path, user feedback,
+screen name. Also read the CEO plan if one exists (it adds strategic context).
+
+Read `DESIGN.md` if it exists in the repo root. These tokens take priority for
+system-level values (fonts, brand colors, spacing scale).
+
+Then check for prior finalized.html. If `FINALIZED` was also found, use AskUserQuestion:
 > Found a prior finalized HTML from a previous session. Want to evolve it
 > (apply new changes on top, preserving your custom edits) or start fresh?
 > A) Evolve — iterate on the existing HTML
 > B) Start fresh — regenerate from the approved mockup
 
 If evolve: read the existing HTML. Apply changes on top during Step 3.
-If fresh: proceed normally.
+If fresh or no finalized.html: proceed to Step 1 with the approved PNG as the
+visual reference.
+
+### Case B: CEO plan and/or design variants exist, but no approved.json
+
+If `CEO_PLAN` or `VARIANTS` was found but no `APPROVED`:
+
+Read whichever context exists:
+- If CEO plan found: read it and summarize the product vision and design requirements.
+- If variant PNGs found: show them inline using the Read tool.
+- If DESIGN.md found: read it for design tokens and constraints.
+
+Use AskUserQuestion:
+> Found [CEO plan from /plan-ceo-review | design review variants from /plan-design-review | both]
+> but no approved design mockup.
+> A) Run /design-shotgun — explore design variants based on the existing plan context
+> B) Skip mockups — I'll design the HTML directly from the plan context
+> C) I have a PNG — let me provide the path
+
+If A: tell the user to run /design-shotgun, then come back to /design-html.
+If B: proceed to Step 1 in "plan-driven mode." There is no approved PNG, the plan is
+the source of truth. Ask the user for a screen name to use for the output directory
+(e.g., "landing-page", "dashboard", "pricing").
+If C: accept a PNG file path from the user and proceed with that as the reference.
+
+### Case C: Nothing found (clean slate)
+
+If none of the above produced any context:
+
+Use AskUserQuestion:
+> No design context found for this project. How do you want to start?
+> A) Run /plan-ceo-review first — think through the product strategy before designing
+> B) Run /plan-design-review first — design review with visual mockups
+> C) Run /design-shotgun — jump straight to visual design exploration
+> D) Just describe it — tell me what you want and I'll design the HTML live
+
+If A, B, or C: tell the user to run that skill, then come back to /design-html.
+If D: proceed to Step 1 in "freeform mode." Ask the user for a screen name.
 
-5. If no `approved.json` found, use AskUserQuestion:
-> No approved design found. You need a mockup first.
-> A) Run /design-shotgun — explore design variants and approve one
-> B) I have a PNG — let me provide the path
+### Context summary
 
-If B: accept a PNG file path from the user and proceed with that as the reference.
+After routing, output a brief context summary:
+- **Mode:** approved-mockup | plan-driven | freeform | evolve
+- **Visual reference:** path to approved PNG, or "none (plan-driven)" or "none (freeform)"
+- **CEO plan:** path or "none"
+- **Design tokens:** "DESIGN.md" or "none"
+- **Screen name:** from approved.json, user-provided, or inferred from CEO plan
 
 ---
 


@@ 601,10 662,22 @@ This returns colors, typography, layout structure, and component inventory via G
 2. If `$D` is not available, read the approved PNG inline using the Read tool.
    Describe the visual layout, colors, typography, and component structure yourself.
 
-3. Read `DESIGN.md` tokens. These override any extracted values for system-level
+3. If in plan-driven or freeform mode (no approved PNG), design from context:
+   - **Plan-driven:** read the CEO plan and/or design review notes. Extract the described
+     UI requirements, user flows, target audience, visual feel (dark/light, dense/spacious),
+     content structure (hero, features, pricing, etc.), and design constraints. Build an
+     implementation spec from the plan's prose rather than a visual reference.
+   - **Freeform:** use AskUserQuestion to gather what the user wants to build. Ask about:
+     purpose/audience, visual feel (dark/light, playful/serious, dense/spacious),
+     content structure (hero, features, pricing, etc.), and any reference sites they like.
+   In both cases, describe the intended visual layout, colors, typography, and
+   component structure as your implementation spec. Generate realistic content based
+   on the plan or user description (never lorem ipsum).
+
+4. Read `DESIGN.md` tokens. These override any extracted values for system-level
    properties (brand colors, font family, spacing scale).
 
-4. Output an "Implementation spec" summary: colors (hex), fonts (family + weights),
+5. Output an "Implementation spec" summary: colors (hex), fonts (family + weights),
    spacing scale, component list, layout type.
 
 ---


@@ 928,13 1001,17 @@ LOOP:
   1. If server is running, tell user to open http://localhost:PORT/finalized.html
      Otherwise: open <path>/finalized.html
 
-  2. Show approved mockup PNG inline (Read tool) for visual comparison
+  2. If an approved mockup PNG exists, show it inline (Read tool) for visual comparison.
+     If in plan-driven or freeform mode, skip this step.
 
-  3. AskUserQuestion:
-     "The HTML is live in your browser. Here's the approved mockup for comparison.
+  3. AskUserQuestion (adjust wording based on mode):
+     With mockup: "The HTML is live in your browser. Here's the approved mockup for comparison.
       Try: resize the window (text should reflow dynamically),
       click any text (it's editable, layout recomputes instantly).
       What needs to change? Say 'done' when satisfied."
+     Without mockup: "The HTML is live in your browser. Try: resize the window
+      (text should reflow dynamically), click any text (it's editable, layout
+      recomputes instantly). What needs to change? Say 'done' when satisfied."
 
   4. If "done" / "ship it" / "looks good" / "perfect" → exit loop, go to Step 5
 


@@ 981,13 1058,15 @@ If A: write `DESIGN.md` to the repo root with the extracted tokens.
 Write `finalized.json` alongside the HTML:
 ```json
 {
-  "source_mockup": "<approved variant PNG path>",
+  "source_mockup": "<approved variant PNG path or null>",
+  "source_plan": "<CEO plan path or null>",
+  "mode": "<approved-mockup|plan-driven|freeform|evolve>",
   "html_file": "<path to finalized.html or component file>",
   "pretext_tier": "<selected tier>",
   "framework": "<vanilla|react|svelte|vue>",
   "iterations": <number of refinement iterations>,
   "date": "<ISO 8601>",
-  "screen": "<screen name from approved.json>",
+  "screen": "<screen name>",
   "branch": "<current branch>"
 }
 ```


@@ 1004,9 1083,11 @@ Use AskUserQuestion:
 
 ## Important Rules
 
-- **Mockup fidelity over code elegance.** If pixel-matching the approved mockup requires
-  `width: 312px` instead of a CSS grid class, that's correct. The mockup is the source
-  of truth. Code cleanup happens later during component extraction.
+- **Source of truth fidelity over code elegance.** When an approved mockup exists,
+  pixel-match it. If that requires `width: 312px` instead of a CSS grid class, that's
+  correct. When in plan-driven or freeform mode, the user's feedback during the
+  refinement loop is the source of truth. Code cleanup happens later during
+  component extraction.
 
 - **Always use Pretext for text layout.** Even if the design looks simple, Pretext
   ensures correct height computation on resize. The overhead is 30KB. Every page benefits.


@@ 1015,8 1096,9 @@ Use AskUserQuestion:
   not the Write tool to regenerate the entire file. The user may have made manual edits
   via contenteditable that should be preserved.
 
-- **Real content only.** Extract text from the approved mockup. Never use "Lorem ipsum",
-  "Your text here", or placeholder content.
+- **Real content only.** When a mockup exists, extract text from it. In plan-driven mode,
+  use content from the plan. In freeform mode, generate realistic content based on the
+  user's description. Never use "Lorem ipsum", "Your text here", or placeholder content.
 
 - **One page per invocation.** For multi-page designs, run /design-html once per page.
   Each run produces one HTML file.

@@ 3,13 3,14 @@ name: design-html
 preamble-tier: 2
 version: 1.0.0
 description: |
-  Design finalization: takes an approved AI mockup from /design-shotgun and
-  generates production-quality Pretext-native HTML/CSS. Text actually reflows,
-  heights are computed, layouts are dynamic. 30KB overhead, zero deps.
-  Smart API routing: picks the right Pretext patterns for each design type.
-  Use when: "finalize this design", "turn this mockup into HTML", "implement
-  this design", or after /design-shotgun approves a direction.
-  Proactively suggest when user has approved a design in /design-shotgun. (gstack)
+  Design finalization: generates production-quality Pretext-native HTML/CSS.
+  Works with approved mockups from /design-shotgun, CEO plans from /plan-ceo-review,
+  design review context from /plan-design-review, or from scratch with a user
+  description. Text actually reflows, heights are computed, layouts are dynamic.
+  30KB overhead, zero deps. Smart API routing: picks the right Pretext patterns
+  for each design type. Use when: "finalize this design", "turn this into HTML",
+  "build me a page", "implement this design", or after any planning skill.
+  Proactively suggest when user has approved a design or has a plan ready. (gstack)
 allowed-tools:
   - Bash
   - Read


@@ 42,37 43,97 @@ around obstacles.
 eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
 ```
 
-1. Find the most recent `approved.json`:
+Detect what design context exists for this project. Run all four checks:
+
 ```bash
 setopt +o nomatch 2>/dev/null || true
-ls -t ~/.gstack/projects/$SLUG/designs/*/approved.json 2>/dev/null | head -1
+_CEO=$(ls -t ~/.gstack/projects/$SLUG/ceo-plans/*.md 2>/dev/null | head -1)
+[ -n "$_CEO" ] && echo "CEO_PLAN: $_CEO" || echo "NO_CEO_PLAN"
 ```
 
-2. If found, read it. Extract: approved variant PNG path, user feedback, screen name.
+```bash
+setopt +o nomatch 2>/dev/null || true
+_APPROVED=$(ls -t ~/.gstack/projects/$SLUG/designs/*/approved.json 2>/dev/null | head -1)
+[ -n "$_APPROVED" ] && echo "APPROVED: $_APPROVED" || echo "NO_APPROVED"
+```
 
-3. Read `DESIGN.md` if it exists in the repo root. These tokens take priority for
-   system-level values (fonts, brand colors, spacing scale).
+```bash
+setopt +o nomatch 2>/dev/null || true
+_VARIANTS=$(ls -t ~/.gstack/projects/$SLUG/designs/*/variant-*.png 2>/dev/null | head -1)
+[ -n "$_VARIANTS" ] && echo "VARIANTS: $_VARIANTS" || echo "NO_VARIANTS"
+```
 
-4. **Evolve mode:** Check for prior output:
 ```bash
 setopt +o nomatch 2>/dev/null || true
-ls -t ~/.gstack/projects/$SLUG/designs/*/finalized.html 2>/dev/null | head -1
+_FINALIZED=$(ls -t ~/.gstack/projects/$SLUG/designs/*/finalized.html 2>/dev/null | head -1)
+[ -n "$_FINALIZED" ] && echo "FINALIZED: $_FINALIZED" || echo "NO_FINALIZED"
+[ -f DESIGN.md ] && echo "DESIGN_MD: exists" || echo "NO_DESIGN_MD"
 ```
-If a prior `finalized.html` exists, use AskUserQuestion:
+
+Now route based on what was found. Check these cases in order:
+
+### Case A: approved.json exists (design-shotgun ran)
+
+If `APPROVED` was found, read it. Extract: approved variant PNG path, user feedback,
+screen name. Also read the CEO plan if one exists (it adds strategic context).
+
+Read `DESIGN.md` if it exists in the repo root. These tokens take priority for
+system-level values (fonts, brand colors, spacing scale).
+
+Then check for prior finalized.html. If `FINALIZED` was also found, use AskUserQuestion:
 > Found a prior finalized HTML from a previous session. Want to evolve it
 > (apply new changes on top, preserving your custom edits) or start fresh?
 > A) Evolve — iterate on the existing HTML
 > B) Start fresh — regenerate from the approved mockup
 
 If evolve: read the existing HTML. Apply changes on top during Step 3.
-If fresh: proceed normally.
+If fresh or no finalized.html: proceed to Step 1 with the approved PNG as the
+visual reference.
+
+### Case B: CEO plan and/or design variants exist, but no approved.json
+
+If `CEO_PLAN` or `VARIANTS` was found but no `APPROVED`:
+
+Read whichever context exists:
+- If CEO plan found: read it and summarize the product vision and design requirements.
+- If variant PNGs found: show them inline using the Read tool.
+- If DESIGN.md found: read it for design tokens and constraints.
+
+Use AskUserQuestion:
+> Found [CEO plan from /plan-ceo-review | design review variants from /plan-design-review | both]
+> but no approved design mockup.
+> A) Run /design-shotgun — explore design variants based on the existing plan context
+> B) Skip mockups — I'll design the HTML directly from the plan context
+> C) I have a PNG — let me provide the path
+
+If A: tell the user to run /design-shotgun, then come back to /design-html.
+If B: proceed to Step 1 in "plan-driven mode." There is no approved PNG, the plan is
+the source of truth. Ask the user for a screen name to use for the output directory
+(e.g., "landing-page", "dashboard", "pricing").
+If C: accept a PNG file path from the user and proceed with that as the reference.
+
+### Case C: Nothing found (clean slate)
+
+If none of the above produced any context:
+
+Use AskUserQuestion:
+> No design context found for this project. How do you want to start?
+> A) Run /plan-ceo-review first — think through the product strategy before designing
+> B) Run /plan-design-review first — design review with visual mockups
+> C) Run /design-shotgun — jump straight to visual design exploration
+> D) Just describe it — tell me what you want and I'll design the HTML live
+
+If A, B, or C: tell the user to run that skill, then come back to /design-html.
+If D: proceed to Step 1 in "freeform mode." Ask the user for a screen name.
 
-5. If no `approved.json` found, use AskUserQuestion:
-> No approved design found. You need a mockup first.
-> A) Run /design-shotgun — explore design variants and approve one
-> B) I have a PNG — let me provide the path
+### Context summary
 
-If B: accept a PNG file path from the user and proceed with that as the reference.
+After routing, output a brief context summary:
+- **Mode:** approved-mockup | plan-driven | freeform | evolve
+- **Visual reference:** path to approved PNG, or "none (plan-driven)" or "none (freeform)"
+- **CEO plan:** path or "none"
+- **Design tokens:** "DESIGN.md" or "none"
+- **Screen name:** from approved.json, user-provided, or inferred from CEO plan
 
 ---
 


@@ 87,10 148,22 @@ This returns colors, typography, layout structure, and component inventory via G
 2. If `$D` is not available, read the approved PNG inline using the Read tool.
    Describe the visual layout, colors, typography, and component structure yourself.
 
-3. Read `DESIGN.md` tokens. These override any extracted values for system-level
+3. If in plan-driven or freeform mode (no approved PNG), design from context:
+   - **Plan-driven:** read the CEO plan and/or design review notes. Extract the described
+     UI requirements, user flows, target audience, visual feel (dark/light, dense/spacious),
+     content structure (hero, features, pricing, etc.), and design constraints. Build an
+     implementation spec from the plan's prose rather than a visual reference.
+   - **Freeform:** use AskUserQuestion to gather what the user wants to build. Ask about:
+     purpose/audience, visual feel (dark/light, playful/serious, dense/spacious),
+     content structure (hero, features, pricing, etc.), and any reference sites they like.
+   In both cases, describe the intended visual layout, colors, typography, and
+   component structure as your implementation spec. Generate realistic content based
+   on the plan or user description (never lorem ipsum).
+
+4. Read `DESIGN.md` tokens. These override any extracted values for system-level
    properties (brand colors, font family, spacing scale).
 
-4. Output an "Implementation spec" summary: colors (hex), fonts (family + weights),
+5. Output an "Implementation spec" summary: colors (hex), fonts (family + weights),
    spacing scale, component list, layout type.
 
 ---


@@ 414,13 487,17 @@ LOOP:
   1. If server is running, tell user to open http://localhost:PORT/finalized.html
      Otherwise: open <path>/finalized.html
 
-  2. Show approved mockup PNG inline (Read tool) for visual comparison
+  2. If an approved mockup PNG exists, show it inline (Read tool) for visual comparison.
+     If in plan-driven or freeform mode, skip this step.
 
-  3. AskUserQuestion:
-     "The HTML is live in your browser. Here's the approved mockup for comparison.
+  3. AskUserQuestion (adjust wording based on mode):
+     With mockup: "The HTML is live in your browser. Here's the approved mockup for comparison.
       Try: resize the window (text should reflow dynamically),
       click any text (it's editable, layout recomputes instantly).
       What needs to change? Say 'done' when satisfied."
+     Without mockup: "The HTML is live in your browser. Try: resize the window
+      (text should reflow dynamically), click any text (it's editable, layout
+      recomputes instantly). What needs to change? Say 'done' when satisfied."
 
   4. If "done" / "ship it" / "looks good" / "perfect" → exit loop, go to Step 5
 


@@ 467,13 544,15 @@ If A: write `DESIGN.md` to the repo root with the extracted tokens.
 Write `finalized.json` alongside the HTML:
 ```json
 {
-  "source_mockup": "<approved variant PNG path>",
+  "source_mockup": "<approved variant PNG path or null>",
+  "source_plan": "<CEO plan path or null>",
+  "mode": "<approved-mockup|plan-driven|freeform|evolve>",
   "html_file": "<path to finalized.html or component file>",
   "pretext_tier": "<selected tier>",
   "framework": "<vanilla|react|svelte|vue>",
   "iterations": <number of refinement iterations>,
   "date": "<ISO 8601>",
-  "screen": "<screen name from approved.json>",
+  "screen": "<screen name>",
   "branch": "<current branch>"
 }
 ```


@@ 490,9 569,11 @@ Use AskUserQuestion:
 
 ## Important Rules
 
-- **Mockup fidelity over code elegance.** If pixel-matching the approved mockup requires
-  `width: 312px` instead of a CSS grid class, that's correct. The mockup is the source
-  of truth. Code cleanup happens later during component extraction.
+- **Source of truth fidelity over code elegance.** When an approved mockup exists,
+  pixel-match it. If that requires `width: 312px` instead of a CSS grid class, that's
+  correct. When in plan-driven or freeform mode, the user's feedback during the
+  refinement loop is the source of truth. Code cleanup happens later during
+  component extraction.
 
 - **Always use Pretext for text layout.** Even if the design looks simple, Pretext
   ensures correct height computation on resize. The overhead is 30KB. Every page benefits.


@@ 501,8 582,9 @@ Use AskUserQuestion:
   not the Write tool to regenerate the entire file. The user may have made manual edits
   via contenteditable that should be preserved.
 
-- **Real content only.** Extract text from the approved mockup. Never use "Lorem ipsum",
-  "Your text here", or placeholder content.
+- **Real content only.** When a mockup exists, extract text from it. In plan-driven mode,
+  use content from the plan. In freeform mode, generate realistic content based on the
+  user's description. Never use "Lorem ipsum", "Your text here", or placeholder content.
 
 - **One page per invocation.** For multi-page designs, run /design-html once per page.
   Each run produces one HTML file.

@@ 13,7 13,7 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples.
 | [`/investigate`](#investigate) | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. |
 | [`/design-review`](#design-review) | **Designer Who Codes** | Live-site visual audit + fix loop. 80-item audit, then fixes what it finds. Atomic commits, before/after screenshots. |
 | [`/design-shotgun`](#design-shotgun) | **Design Explorer** | Generate multiple AI design variants, open a comparison board in your browser, and iterate until you approve a direction. Taste memory biases toward your preferences. |
-| [`/design-html`](#design-html) | **Design Engineer** | Takes an approved mockup from `/design-shotgun` and generates production-quality Pretext-native HTML. Text reflows on resize, heights adjust to content. Smart API routing per design type. Framework detection for React/Svelte/Vue. |
+| [`/design-html`](#design-html) | **Design Engineer** | Generates production-quality Pretext-native HTML. Works with approved mockups, CEO plans, design reviews, or from scratch. Text reflows on resize, heights adjust to content. Smart API routing per design type. Framework detection for React/Svelte/Vue. |
 | [`/qa`](#qa) | **QA Lead** | Test your app, find bugs, fix them with atomic commits, re-verify. Auto-generates regression tests for every fix. |
 | [`/qa-only`](#qa) | **QA Reporter** | Same methodology as /qa but report only. Use when you want a pure bug report without code changes. |
 | [`/ship`](#ship) | **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstraps test frameworks if you don't have one. One command. |


@@ 425,7 425,7 @@ You know the feeling. You have a feature, a page, a landing screen... and you're
 5. You click "Approve" on the one you like, or give feedback for another round
 6. The approved variant saves to `~/.gstack/projects/$SLUG/designs/` with an `approved.json`
 
-That `approved.json` is what `/design-html` reads. The design pipeline chains: shotgun picks the direction, design-html renders it as working code.
+That `approved.json` is one way to feed `/design-html`. The design pipeline chains: shotgun picks the direction, design-html renders it as working code. But `/design-html` also works with CEO plans, design reviews, or just a description.
 
 ### Taste memory
 


@@ 457,7 457,9 @@ This is my **design-to-code mode**.
 
 Every AI code generation tool produces static CSS. Hardcoded heights. Text that overflows on resize. Breakpoints that snap instead of flowing. The output looks right at exactly one viewport size and breaks at every other.
 
-`/design-html` fixes this. It takes the approved mockup from `/design-shotgun` and generates HTML using [Pretext](https://github.com/chenglou/pretext) by Cheng Lou (ex-React core, Midjourney frontend). Pretext is a 15KB library that computes text layout without DOM measurement. Text reflows. Heights adjust to content. Cards size themselves. Chat bubbles shrinkwrap. All sub-millisecond, all dynamic.
+`/design-html` fixes this. It generates HTML using [Pretext](https://github.com/chenglou/pretext) by Cheng Lou (ex-React core, Midjourney frontend). Pretext is a 15KB library that computes text layout without DOM measurement. Text reflows. Heights adjust to content. Cards size themselves. Chat bubbles shrinkwrap. All sub-millisecond, all dynamic.
+
+It works with multiple input sources: an approved mockup from `/design-shotgun`, a CEO plan from `/plan-ceo-review`, design review context from `/plan-design-review`, a PNG you provide, or just a description of what you want. It detects what context exists and asks how you want to proceed.
 
 ### Smart API routing