renn-studio 0.6.0

package/renn/workflows/design-stage.md

@@ -0,0 +1,2019 @@
+<purpose>
+Run the full design pipeline for a UI stage or an entire project independently of plan-stage.
+
+Dual-mode: operates in stage-level mode (single stage, invoked by design-screens or restyle) or project-level mode (all UI stages, invoked by design-system without a stage number). Use this workflow when a stage involves visual UI work and needs design artifacts (stylekit, screen prototypes, implementation guide) before architecture planning. Handles UI detection, UX interview, UX synthesis, design interview, Phase 1 (stylekit), Phase 2 (screens), implementation guide generation, and design artifact commits.
+</purpose>
+
+<core_principle>
+Fresh context per agent. Orchestrator stays lean (~15%), each subagent gets 100% fresh 200k. Intel.md loaded early and passed to ALL agents to constrain scope. This is an extraction of plan-stage's design pipeline into a standalone command -- spawn templates and design logic are preserved verbatim to maintain artifact parity.
+</core_principle>
+
+<process>
+
+<step name="validate_environment" priority="first">
+Validate .renn/ exists and resolve model profile:
+
+```bash
+ls .renn/ 2>/dev/null
+```
+
+**If not found:** Error - user should run `/renn.start` first.
+
+**Resolve model profile for agent spawning:**
+
+```bash
+MODEL_PROFILE=$(cat .renn/config.json 2>/dev/null | grep -o '"horsepower"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | max | balanced | eco |
+|-------|---------|----------|--------|
+| renn-stage-scout | opus | sonnet | haiku |
+| renn-architect | opus | opus | sonnet |
+| renn-plan-reviewer | sonnet | sonnet | haiku |
+| renn-designer | opus | sonnet | sonnet |
+| renn-design-reviewer | sonnet | sonnet | haiku |
+
+Store resolved models for use in Task calls below.
+</step>
+
+<step name="parse_arguments">
+Extract from $ARGUMENTS:
+
+- Stage number (integer or decimal like `2.1`) -- OPTIONAL in project-level mode
+- `--skip-ux-interview` flag to skip UX interview
+- `--restyle` flag to enter restyle mode (invoked by renn.restyle command)
+- `--phase-1-only` flag to stop after Phase 1 (invoked by renn.design-system command)
+- `--phase-2-only` flag to skip to Phase 2 (invoked by renn.design-screens command)
+
+**Determine mode:**
+
+If `--phase-1-only` flag is present AND no stage number is provided:
+  Set `PROJECT_LEVEL=true`
+Else:
+  Set `PROJECT_LEVEL=false`
+
+**If PROJECT_LEVEL=true:** Skip stage number parsing, normalization, and research check. These are stage-scoped operations that do not apply in project-level mode. Continue to validate_stage.
+
+**If PROJECT_LEVEL=false:**
+
+**If no stage number:** Detect next unplanned stage from track.
+
+**Normalize stage to zero-padded format:**
+
+```bash
+# Normalize stage number (8 -> 08, but preserve decimals like 2.1 -> 02.1)
+if [[ "$STAGE" =~ ^[0-9]+$ ]]; then
+  STAGE=$(printf "%02d" "$STAGE")
+elif [[ "$STAGE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  STAGE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+fi
+```
+
+**Check for existing research:**
+
+```bash
+ls .renn/stages/${STAGE}-*/*-research.md 2>/dev/null
+```
+</step>
+
+<step name="validate_stage">
+**If PROJECT_LEVEL=true:** Skip single-stage validation. Instead, scan track.md for ALL stages and identify which are UI stages.
+
+**Project-level track scanning:**
+
+```bash
+# Extract all stage headings and goals from track.md
+# Track uses "### Stage N:" format (anchored to ### headings)
+grep -A5 "^### Stage [0-9]*:" .renn/track.md | grep -v "^\-\-$"
+```
+
+For each stage heading found, check if it contains a [UI] tag:
+
+```
+For each stage heading:
+  If heading contains [UI] (e.g., "### Stage 5: Dashboard [UI]") -> this is a UI stage
+  Otherwise -> not a UI stage (skip)
+```
+
+No keyword scoring. The [UI] tag is authoritative.
+
+Collect results:
+- `UI_STAGES` -- list of stage numbers + names + goals that have [UI] tag in their heading
+- `ALL_UI_GOALS` -- combined goal text from all UI stages
+
+Validate at least one UI stage exists:
+
+```bash
+if [ ${#UI_STAGES[@]} -eq 0 ]; then
+  echo "No UI stages found in track.md. Design pipeline requires at least one UI stage."
+  # ERROR and exit
+fi
+```
+
+Display discovered UI stages:
+
+```
+Found {N} UI stages:
+  - Stage 3: Dashboard -- Main dashboard with data visualization
+  - Stage 5: Settings -- User settings page
+
+Design system will cover all {N} UI stages.
+```
+
+**If PROJECT_LEVEL=false:**
+
+```bash
+# Strip leading zeros for track.md lookup (track uses "Stage 1:", not "Stage 01:")
+STAGE_UNPADDED=$(echo "$STAGE" | sed 's/^0\+\([0-9]\)/\1/')
+grep -A5 "^### Stage ${STAGE_UNPADDED}:" .renn/track.md 2>/dev/null
+```
+
+**If not found:** Error with available stages. **If found:** Extract stage number, name, description.
+</step>
+
+<step name="ensure_stage_directory">
+**If PROJECT_LEVEL=true:** Skip stage directory creation. Set project-level variable defaults instead.
+
+```bash
+# No stage directory in project-level mode
+STAGE_DIR=""  # Not used in project-level mode
+INTEL_CONTENT=""  # No per-stage intel exists for project-level
+STAGE_NAME="design-system"  # For display purposes
+STAGE="project"  # For commit messages
+COMMIT_PREFIX="design"  # For commit messages (used by handle_design)
+COMMIT_MSG_SCOPE="project design system"  # For commit message body text
+
+# Project-level variables are still extracted from brief.md (they are project-scoped already)
+PROJECT_NAME=$(head -1 .renn/brief.md 2>/dev/null | sed 's/^# //')
+PLATFORM=$(grep -m1 '^\*\*Platform:\*\*' .renn/brief.md 2>/dev/null | sed 's/\*\*Platform:\*\* //')
+VIEWPORT_RAW=$(grep -m1 '^\*\*Viewport:\*\*' .renn/brief.md 2>/dev/null | sed 's/\*\*Viewport:\*\* //')
+```
+
+Display: `Using project-level mode (no stage directory). Designing for all UI stages.`
+
+**If PROJECT_LEVEL=false:**
+
+```bash
+# STAGE is already normalized (08, 02.1, etc.) from parse_arguments
+STAGE_DIR=$(ls -d .renn/stages/${STAGE}-* 2>/dev/null | head -1)
+if [ -z "$STAGE_DIR" ]; then
+  # Create stage directory from track name
+  # Anchor to ### headings to avoid matching list items (which contain markdown ** and descriptions)
+  STAGE_UNPADDED=$(echo "$STAGE" | sed 's/^0\+\([0-9]\)/\1/')
+  STAGE_NAME=$(grep "^### Stage ${STAGE_UNPADDED}:" .renn/track.md | head -1 | sed 's/^### Stage [0-9]*: //' | sed 's/ \[UI\]$//' | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+  mkdir -p ".renn/stages/${STAGE}-${STAGE_NAME}"
+  STAGE_DIR=".renn/stages/${STAGE}-${STAGE_NAME}"
+fi
+
+# Set COMMIT_PREFIX for stage-level mode (symmetry with project-level)
+COMMIT_PREFIX="${STAGE}"
+COMMIT_MSG_SCOPE="Stage ${STAGE}: ${STAGE_NAME}"
+
+# Load intel.md immediately - this informs ALL downstream agents
+INTEL_CONTENT=$(cat "${STAGE_DIR}"/*-intel.md 2>/dev/null)
+
+# Extract project name from brief.md heading (used in designer spawn)
+PROJECT_NAME=$(head -1 .renn/brief.md 2>/dev/null | sed 's/^# //')
+
+# Extract viewport context from brief.md (used in Phase 1 designer spawn)
+PLATFORM=$(grep -m1 '^\*\*Platform:\*\*' .renn/brief.md 2>/dev/null | sed 's/\*\*Platform:\*\* //')
+VIEWPORT_RAW=$(grep -m1 '^\*\*Viewport:\*\*' .renn/brief.md 2>/dev/null | sed 's/\*\*Viewport:\*\* //')
+```
+
+**CRITICAL:** Store `INTEL_CONTENT` now. It must be passed to:
+- **Scout** -- constrains what to research (locked decisions vs Claude's discretion)
+- **Designer** -- locked decisions must be honored, not revisited
+- **Reviewer** -- verifies design respects user's stated vision
+
+If intel.md exists, display: `Using stage context from: ${STAGE_DIR}/*-intel.md`
+</step>
+
+<step name="handle_research">
+**If PROJECT_LEVEL=true:** Skip handle_research entirely. Research is stage-scoped; project-level design relies on UX.md (project-level UX research) and the design interview for design preferences. Set `RESEARCH_CONTENT=""`. Continue to detect_ui_stage.
+
+**If PROJECT_LEVEL=false:**
+
+**If `--phase-2-only` flag is set:** Skip handle_research entirely. Do NOT check config, do NOT check for existing research.md, do NOT offer the scout agent. Research was done during /renn.design-system. Load from disk if available: `RESEARCH_CONTENT=$(cat ${STAGE_DIR}/${STAGE}-research.md 2>/dev/null || echo "")`. If the file does not exist, set `RESEARCH_CONTENT=""` (empty string). Continue to detect_ui_stage.
+
+Check config for research setting:
+
+```bash
+WORKFLOW_RESEARCH=$(cat .renn/config.json 2>/dev/null | grep -o '"research"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+```
+
+**If `checks.research` is `false`:** Skip to detect_ui_stage.
+
+**Otherwise:**
+
+Check for existing research:
+
+```bash
+ls "${STAGE_DIR}"/*-research.md 2>/dev/null
+```
+
+**If research.md exists:**
+- Display: `Using existing research: ${STAGE_DIR}/${STAGE}-research.md`
+- Set `RESEARCH_CONTENT` from the file
+- Skip to detect_ui_stage
+
+**If research.md missing:**
+
+Use AskUserQuestion to offer:
+
+```
+No research found for this stage. Research first?
+
+Options:
+  Yes - Spawn scout to research before designing
+  No  - Proceed to design without research
+```
+
+**If "Yes":**
+
+Display stage banner:
+```
+RENN > SCOUTING STAGE {X}
+
+Spawning scout...
+```
+
+Gather additional context for research prompt:
+
+```bash
+# Get stage description from track (use STAGE_UNPADDED from validate_stage)
+STAGE_DESC=$(grep -A5 "^### Stage ${STAGE_UNPADDED}:" .renn/track.md)
+
+# Get specs if they exist
+SPECS=$(cat .renn/specs.md 2>/dev/null | grep -A100 "## Requirements" | head -50)
+
+# Get prior decisions from pulse.md
+DECISIONS=$(grep -A20 "### Decisions Made" .renn/pulse.md 2>/dev/null)
+
+# INTEL_CONTENT already loaded in ensure_stage_directory
+
+# Read UX.md for scout (if exists)
+UX_CONTENT_FOR_SCOUT=$(cat .renn/research/UX.md 2>/dev/null)
+```
+
+Fill research prompt and spawn:
+
+```markdown
+<objective>
+Research how to implement Stage {stage_number}: {stage_name}
+
+Answer: "What do I need to know to PLAN this stage well?"
+</objective>
+
+<stage_context>
+**IMPORTANT:** If intel.md exists below, it contains user decisions from /renn.discuss-stage.
+
+- **Decisions section** = Locked choices -- research THESE deeply, don't explore alternatives
+- **Claude's Discretion section** = Your freedom areas -- research options, make recommendations
+- **Deferred Ideas section** = Out of scope -- ignore completely
+
+{intel_content}
+</stage_context>
+
+<additional_context>
+**Stage description:**
+{stage_description}
+
+**Specs (if any):**
+{specs}
+
+**Prior decisions from pulse.md:**
+{decisions}
+</additional_context>
+
+<ux_context>
+**UX.md content (if exists -- use for Stage UX Patterns section):**
+
+If UX.md content is present below, generate a ## Stage UX Patterns section in your research.md output. Cross-reference these project-level findings with the specific stage being researched. If no UX.md content below, omit the Stage UX Patterns section.
+
+{ux_content_for_scout}
+</ux_context>
+
+<output>
+Write research findings to: {stage_dir}/{stage}-research.md
+</output>
+```
+
+```
+Task(
+  prompt=research_prompt,
+  subagent_type="renn-stage-scout",
+  model="{scout_model}",
+  description="Research Stage {stage}"
+)
+```
+
+### Handle Scout Return
+
+**`## RESEARCH COMPLETE`:**
+- Display: `Research complete. Proceeding to design...`
+- Set `RESEARCH_CONTENT` from the research file
+- Continue to detect_ui_stage
+
+**`## RESEARCH BLOCKED`:**
+- Display blocker information
+- Offer: 1) Provide more context, 2) Skip research and design anyway, 3) Abort
+- Wait for user response
+
+**If "No" (skip research):**
+- Set `RESEARCH_CONTENT=""`
+- Continue to detect_ui_stage
+</step>
+
+<step name="detect_ui_stage">
+**If `--phase-2-only` flag is set:** Skip UI detection entirely. The user explicitly invoked `renn.design-screens` which is a design command -- UI stage is guaranteed. Set `UI_STAGE=true`. Continue directly to handle_ux_interview (which will also be skipped by --skip-ux-interview).
+
+**If PROJECT_LEVEL=true:** Skip UI detection. The validate_stage step already scanned all stages from track.md for [UI] tags and confirmed at least one UI stage exists. Set `UI_STAGE=true`. The `UI_STAGES` list and `ALL_UI_GOALS` from validate_stage are available for downstream steps (handle_ux_interview and handle_design). Continue to handle_ux_interview.
+
+**If PROJECT_LEVEL=false:**
+
+### UI Detection
+
+Check the stage heading from track.md:
+
+```bash
+STAGE_HEADING=$(grep "^### Stage ${STAGE_UNPADDED}:" .renn/track.md | head -1)
+```
+
+If the heading contains `[UI]` -> set `UI_STAGE=true`.
+If the heading does NOT contain `[UI]` -> this is not a UI stage. **ERROR and exit.** Display:
+
+```
+Stage {N} is not a UI stage (no [UI] tag in track.md heading). Design pipeline is for UI stages only.
+
+Use /renn.plan-stage {N} directly.
+```
+
+No keyword matching. No UNCERTAIN state. The [UI] tag is authoritative.
+
+Store `UI_STAGE` for use by handle_ux_interview and handle_design.
+</step>
+
+<step name="handle_ux_interview">
+**Skip conditions (check in order):**
+1. UX.md does not exist -> skip (display: "No UX.md found. Skipping UX interview. Run /renn.start or /renn.new-milestone to generate UX research.")
+2. `--skip-ux-interview` flag set -> skip
+
+**Read UX context:**
+
+```bash
+UX_CONTENT=$(cat .renn/research/UX.md 2>/dev/null)
+if [ -z "$UX_CONTENT" ]; then
+  echo "No UX.md found. Skipping UX interview."
+  UX_INTERVIEW_ANSWERS=""
+  UX_QUESTIONS_ASKED=0
+fi
+
+# Load stage-specific UX research section
+if [ "$PROJECT_LEVEL" = "true" ]; then
+  # No per-stage research.md in project-level mode (research was skipped)
+  RESEARCH_UX_SECTION=""
+else
+  RESEARCH_UX_SECTION=""
+  if [ -f "${STAGE_DIR}"/*-research.md ]; then
+    RESEARCH_UX_SECTION=$(sed -n '/## Stage UX Patterns/,/^## [^S]/p' "${STAGE_DIR}"/*-research.md 2>/dev/null)
+  fi
+fi
+```
+
+**Display banner:**
+
+**If PROJECT_LEVEL=true:**
+
+```
+RENN > UX INTERVIEW FOR PROJECT
+
+Before visual design, let's discuss how users should experience this project across all UI stages.
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+RENN > UX INTERVIEW FOR STAGE {X}
+
+Before visual design, let's discuss how users should experience this stage.
+```
+
+**Generate 4-6 questions dynamically from UX.md findings (UXIN-04):**
+
+Read UX.md content and extract questions from these categories. **If PROJECT_LEVEL=true:** generate questions spanning ALL UI stages (using `ALL_UI_GOALS` and `UI_STAGES` from validate_stage) instead of a single stage's features. The question categories remain the same -- only the scope of features considered broadens to cover all UI stages. **If PROJECT_LEVEL=false:** generate questions for the single stage as before.
+
+**Plain-language rule:** The user may not be technical. Describe what the user would see or do — never assume they know UX terminology. Replace jargon with behavior descriptions or familiar app references. For example, say "show options one step at a time" instead of "progressive disclosure."
+
+1. **Critical Flows (1-2 questions):** For each critical flow with LOW or MEDIUM friction tolerance in UX.md, generate a question about how that flow should behave in this stage (or across all UI stages in project-level mode). Use third-person framing (UXIN-05):
+   - "When someone [does X] for the first time, should it feel more like [familiar example A] or [familiar example B]?"
+
+2. **Proven Patterns (1-2 questions):** For proven patterns from UX.md that apply to this stage's features (or all UI stages' features in project-level mode), ask whether to adopt the pattern. Describe what the pattern looks like, not what it's called:
+   - "Similar apps let users [behavior description]. Should this work the same way?"
+
+3. **Anti-Pattern Awareness (0-1 questions):** If UX.md identifies anti-patterns relevant to this stage (or any UI stage in project-level mode), generate one awareness question. Describe the bad experience, not the pattern name:
+   - "A common frustration in [domain] apps is [description of bad experience]. When that happens here, how should we handle it?"
+
+4. **Emotional Design (1 question):** Generate one emotional calibration question from UX.md emotional design goals. Direct framing:
+   - "We want people to feel [emotion] when using this. Which approach gets closer to that?"
+
+**Question format (UXIN-02, UXIN-03):**
+
+Every question presented via AskUserQuestion:
+- 2-4 concrete options informed by UX.md findings — describe what the user sees, not the pattern name
+- EVERY question includes a "Let Claude decide" option with research-backed default: "(Research suggests: [UX.md recommendation])"
+- Third-person framing for interaction/flow questions (UXIN-05); direct framing for preference/calibration questions
+- Track `UX_QUESTIONS_ASKED` count (target 4-6)
+
+**Compile answers:**
+
+```xml
+<ux_interview_answers>
+### [Question Topic 1]
+Question: {question text}
+Answer: {user's choice or "Let Claude decide"}
+Research default: {what UX.md recommends}
+
+### [Question Topic 2]
+Question: {question text}
+Answer: {user's choice or "Let Claude decide"}
+Research default: {what UX.md recommends}
+
+...
+</ux_interview_answers>
+```
+
+**Store for downstream:**
+- `UX_INTERVIEW_ANSWERS` -- compiled answers
+- `UX_QUESTIONS_ASKED` -- count for visual interview budget
+- `UX_CONTENT` -- original UX.md content for synthesis
+- `RESEARCH_UX_SECTION` -- stage-specific UX section for synthesis
+</step>
+
+<step name="ux_synthesis">
+**Skip conditions:**
+1. handle_ux_interview was skipped -> skip (`UX_INTERVIEW_ANSWERS` is empty)
+2. `UI_STAGE` is false -> skip
+
+**Synthesize inline (UXSY-03: no agent spawn):**
+
+Read:
+- `UX_CONTENT` (project-level UX.md research)
+- `RESEARCH_UX_SECTION` (stage-specific UX patterns from research.md)
+- `UX_INTERVIEW_ANSWERS` (user decisions from UX interview)
+
+Produce `UX_BRIEF` by combining all three sources into concrete design implications.
+
+**Brief heading differs by mode:**
+- **If PROJECT_LEVEL=true:** `## UX Direction for {PROJECT_NAME}`
+- **If PROJECT_LEVEL=false:** `## UX Direction for Stage {X}: {Name}`
+
+**If PROJECT_LEVEL=true:** Include a `### UI Stages Covered` section after the heading, listing all UI stages from `UI_STAGES`:
+
+```markdown
+### UI Stages Covered
+- Stage 3: Dashboard -- Main dashboard with data visualization
+- Stage 5: Settings -- User settings page
+```
+
+```xml
+<ux_brief>
+
+## UX Direction for {PROJECT_NAME or "Stage {X}: {Name}"}
+
+{IF PROJECT_LEVEL=true:}
+### UI Stages Covered
+- {list each UI stage from UI_STAGES with number, name, and goal}
+
+{END IF}
+
+### Interaction Model
+- [Concrete decisions from interview answers, e.g., "Inline form validation with debounced checks"]
+- [Research-backed defaults for "Let Claude decide" answers, e.g., "Toast notifications for async operations, auto-dismiss 5s"]
+
+### Spacing and Density
+- [Implied from adopted patterns, e.g., "Comfortable density -- 16px base padding, 24px section gaps"]
+- [From UX.md emotional design implications, e.g., "Generous whitespace to achieve calm emotion"]
+
+### Component Implications
+- [From adopted patterns + interview answers, e.g., "Data tables with sortable headers per UX.md proven pattern"]
+- [From anti-pattern avoidance, e.g., "No infinite scroll -- paginate with clear page numbers per UX.md anti-pattern guidance"]
+
+### Flow Design
+- [From critical flow decisions, e.g., "Onboarding: 3-step wizard with skip option and progress indicator"]
+- [From friction tolerance, e.g., "Checkout: minimal friction -- single page, no account required"]
+
+### Emotional Guardrails
+- Primary: [from UX.md + calibration answer, e.g., "confident -- clear feedback at every step"]
+- Avoid: [from UX.md anti-emotion, e.g., "overwhelmed -- progressive disclosure, max 5 options per screen"]
+
+### Research References
+- [Cross-references to UX.md sections that informed decisions]
+- [Pattern names and confidence levels from research]
+
+</ux_brief>
+```
+
+**Rules for synthesis:**
+- For answers where user made a choice: use the user's choice verbatim
+- For "Let Claude decide" answers: use the research-backed default from UX.md
+- Translate abstract UX principles into concrete design implications (spacing values, component types, flow structures)
+- If all answers were "Let Claude decide": produce ux_brief entirely from UX.md research defaults
+- Keep ux_brief concise (30-50 lines). This is a digest, not a research report
+
+**Persist UX_BRIEF to file (EXTR-02):**
+
+**If PROJECT_LEVEL=true:**
+
+```bash
+mkdir -p .renn/design/
+```
+
+Write the UX_BRIEF content to `.renn/design/ux-brief.md` as plain markdown. The file contains the synthesized UX brief sections WITHOUT XML tags -- just the markdown content between `<ux_brief>` and `</ux_brief>`.
+
+Display: `UX brief synthesized and saved to .renn/design/ux-brief.md. Proceeding to design...`
+
+**If PROJECT_LEVEL=false:**
+
+Write the UX_BRIEF content to `${STAGE_DIR}/${STAGE}-ux-brief.md` as plain markdown. The file contains the synthesized UX brief sections WITHOUT XML tags -- just the markdown content between `<ux_brief>` and `</ux_brief>`.
+
+This file survives `/clear` and is loaded by plan-stage in its read_context_files step.
+
+Display: `UX brief synthesized and saved to ${STAGE_DIR}/${STAGE}-ux-brief.md. Proceeding to design...`
+
+**File format (both modes):**
+
+```markdown
+## UX Direction for {PROJECT_NAME or "Stage {X}: {Name}"}
+
+### UI Stages Covered (project-level only)
+- ...
+
+### Interaction Model
+- ...
+
+### Spacing and Density
+- ...
+
+### Component Implications
+- ...
+
+### Flow Design
+- ...
+
+### Emotional Guardrails
+- ...
+
+### Research References
+- ...
+```
+
+**Store:** `UX_BRIEF` variable for handle_design and designer context.
+</step>
+
+<step name="handle_design">
+
+**Load commit config for design artifact commits:**
+
+```bash
+COMMIT_PLANNING_DOCS=$(cat .renn/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+git check-ignore -q .renn 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+### UI Detection
+
+UI detection has already run in detect_ui_stage. The result is confirmed:
+
+- `UI_STAGE=true`: Continue to Existing Design Detection.
+
+(design-stage validated `UI_STAGE=true` in detect_ui_stage. Non-UI stages error and exit at that step.)
+
+### Existing Design Detection (PLAN-03 partial)
+
+```bash
+# Check if screens for this stage already exist in global location
+# This requires checking if the stage previously ran Phase 2 and produced screens
+# Look for design output markers in recap files
+grep -l "Screen Specs" "${STAGE_DIR}"/*-recap.md 2>/dev/null
+```
+
+If a recap references screen specs and no `--force` flag: Display "Using existing design from prior run.". Store design paths for downstream. Skip to generate_implementation_guide.
+
+### Mode Determination (PLAN-03)
+
+```bash
+ls .renn/design/stylekit.yaml 2>/dev/null
+ls .renn/codebase/DESIGN.md 2>/dev/null
+```
+
+**Phase 2 only mode override (when --phase-2-only flag is set):**
+
+If `PHASE_2_ONLY=true`:
+- Check `ls .renn/design/stylekit.yaml 2>/dev/null`
+- If stylekit.yaml does NOT exist: **ERROR** -- Display: "No design system found at .renn/design/stylekit.yaml\n\nRun /renn.design-system first to create the design system,\nthen run /renn.design-screens {N} to create screen prototypes." STOP.
+- If stylekit.yaml exists: Set `DESIGN_MODE="screens_only"`. Skip normal mode determination. Skip Restyle Trigger. Jump directly to Phase 2.
+- Load UX brief from disk (project-level path first, stage-level fallback):
+  ```bash
+  UX_BRIEF=$(cat .renn/design/ux-brief.md 2>/dev/null)
+  if [ -z "$UX_BRIEF" ]; then
+    UX_BRIEF=$(cat ${STAGE_DIR}/${STAGE}-ux-brief.md 2>/dev/null)
+  fi
+  ```
+- Load research from disk (if not already loaded): `RESEARCH_CONTENT=$(cat ${STAGE_DIR}/${STAGE}-research.md 2>/dev/null)` (belt-and-suspenders with handle_research skip)
+
+**Restyle mode override (when --restyle flag is set):**
+
+If `RESTYLE_MODE=true`:
+- Check `ls .renn/design/stylekit.yaml 2>/dev/null`
+- If stylekit.yaml does NOT exist: **ERROR** -- Display: "No existing design to restyle. Run `/renn.design-system` first." STOP.
+- If stylekit.yaml exists: Set `DESIGN_MODE="screens_only"`. Skip the normal priority order below. Jump directly to the Restyle Trigger (PLAN-07) section.
+
+**Normal mode determination (when --restyle flag is NOT set):**
+
+Priority order (check in this sequence):
+1. If stylekit.yaml exists: `DESIGN_MODE="screens_only"` (approved design system takes precedence)
+2. Else if .renn/codebase/DESIGN.md exists: `DESIGN_MODE="translate"` (brownfield design detected)
+3. Else: `DESIGN_MODE="full"` (greenfield, no existing design)
+
+### Translate Mode Checkpoint (only when DESIGN_MODE="translate")
+
+**If `DESIGN_MODE` is NOT "translate": Skip this subsection.**
+
+Present `checkpoint:decision`:
+
+```
+Existing design patterns detected in .renn/codebase/DESIGN.md
+
+Your project already has a visual design system. How should RENN handle it?
+
+Options:
+  Absorb - Extract existing patterns into RENN stylekit as-is (fastest, no interview)
+  Extend - Extract existing patterns + discuss enhancements (balanced)
+  Replace - Ignore existing patterns, create fresh design system (full interview)
+
+Select: absorb, extend, or replace
+```
+
+Routing:
+- `absorb`: Set `TRANSLATE_STRATEGY="absorb"`. Skip the design interview entirely. Read `.renn/codebase/DESIGN.md` content into `TRANSLATION_CONTEXT`. Display: "Absorbing existing design. Skipping interview..."
+- `extend`: Set `TRANSLATE_STRATEGY="extend"`. Read `.renn/codebase/DESIGN.md` content into `TRANSLATION_CONTEXT`. Continue to the scoped interview (see Scoped Interview below).
+- `replace`: Set `DESIGN_MODE="full"`. Display: "Replacing existing design. Running full interview..." Continue to existing greenfield flow (design interview, Phase 1, etc.) as if DESIGN.md did not exist.
+
+### Scoped Interview (only when TRANSLATE_STRATEGY="extend")
+
+**If `TRANSLATE_STRATEGY` is NOT "extend": Skip this subsection.**
+
+This is a shortened version of the full design interview, focused on gaps in the existing design.
+
+#### Step 1: Analyze DESIGN.md for Gaps
+
+Read TRANSLATION_CONTEXT (the DESIGN.md content). For each core design question, determine if DESIGN.md already answers it:
+
+| Core Question | Already Answered If |
+|---------------|---------------------|
+| Visual style | DESIGN.md describes a clear visual personality |
+| Color direction | Color System section has a defined palette |
+| Typography | Typography section has specific font families |
+| Layout density | Component Inventory shows consistent spacing patterns |
+| Dark mode | Dark Mode section has a strategy other than "not implemented" |
+| Responsive | Component Inventory or Visual Patterns show responsive behavior |
+
+Track which questions are UNANSWERED (gaps).
+
+#### Step 2: Generate Extension Gray Areas
+
+Generate 2-3 gray areas based on what DESIGN.md is MISSING. These are aspects where the existing design has no clear direction and the user should weigh in.
+
+Example: If DESIGN.md has colors and fonts but no dark mode and no spacing scale:
+- "Dark mode strategy" -- Should we add dark mode support?
+- "Spacing refinement" -- Your current spacing seems ad-hoc. Standardize to a scale?
+
+#### Step 3: Deep-Dive Gaps
+
+For each unanswered core question and generated gray area, use AskUserQuestion with 2-4 options (following the same pattern as the full interview):
+- Include "Let Claude decide" option on every question
+- Follow the same recommendation guidelines (subjective = recommend specific, technical = recommend "Let Claude decide")
+
+Target: 3-7 total questions (shorter than the full interview's 8-15).
+
+#### Step 4: Compile Extension Preferences
+
+Compile answers into `DESIGN_EXTENSION_PREFERENCES` using this format:
+
+```xml
+<design_extension_preferences>
+
+## Extension Direction
+
+### Aspects Preserved from Existing Design
+- Color system: {summary from DESIGN.md}
+- Typography: {summary from DESIGN.md}
+- {other preserved aspects}
+
+### Aspects Extended
+{For each gap where user answered:}
+### [Gap Area]
+Pick: {user's choice OR "Designer's choice"}
+Context: {any elaboration}
+
+### Designer Autonomy
+The following aspects are marked as "Designer's choice":
+- {list of "Let Claude decide" items}
+
+</design_extension_preferences>
+```
+
+Display: "Extension preferences captured. Proceeding to design system creation..."
+
+### Restyle Trigger (PLAN-07)
+
+Only when `DESIGN_MODE="screens_only"` (existing stylekit detected):
+
+**If RESTYLE_MODE=true:** Skip the restyle checkpoint entirely. Set `DESIGN_MODE="screens_only"`.
+
+Display:
+```
+Restyling: creating new screen prototypes with existing design system.
+To create an entirely new design system, run /renn.design-system instead.
+```
+
+**If RESTYLE_MODE is NOT set (normal flow):** Present the existing checkpoint:
+
+```
+Existing stylekit found at .renn/design/stylekit.yaml
+
+Options:
+  Use existing - Create new screens using current design system
+  Restyle - Create a new visual direction (replaces current stylekit)
+
+Select: use-existing or restyle
+```
+
+If `use-existing`: Continue with `DESIGN_MODE="screens_only"`.
+If `restyle`: Set `DESIGN_MODE="full"`. Designer receives existing stylekit as reference context.
+
+### Design Interview
+
+**If `DESIGN_MODE="screens_only"`: Skip interview entirely.** Preferences are already baked into the existing stylekit.
+
+**If `DESIGN_MODE="translate"` and `TRANSLATE_STRATEGY="absorb"`: Skip interview entirely.** Designer will extract existing patterns as-is.
+
+**If `DESIGN_MODE="translate"` and `TRANSLATE_STRATEGY="extend"`: Skip this section.** The scoped interview above already captured extension preferences.
+
+**If `DESIGN_MODE="full"`:** Run the progressive design interview.
+
+Display banner:
+
+**If PROJECT_LEVEL=true:**
+
+```
+RENN > PROJECT DESIGN -- DESIGN INTERVIEW
+
+Before creating your project design system, let me understand your vision.
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+RENN > DESIGNING STAGE {X} -- DESIGN INTERVIEW
+
+Before creating your design system, let me understand your vision.
+```
+
+If this is a restyle (DESIGN_MODE was set to "full" via the restyle trigger), acknowledge it: "You're restyling. Let me ask about your new direction."
+
+#### Step 1: Analyze Project Context
+
+Read available project context to generate design-relevant gray areas:
+
+1. Read brief.md for project domain and value proposition
+2. Read stage goal from track.md for what's being built
+3. Read research.md (if exists) for technical context
+4. Read intel.md (if exists) for existing decisions
+
+Generate 3-5 gray areas SPECIFIC to this project. These are design decisions that would change the outcome and the user should weigh in on.
+
+**Plain-language rule:** The user may not be technical. Describe what they'd see or experience — not design terminology. Use familiar app references where helpful.
+
+Examples:
+
+For a "personal dashboard" project:
+- "How packed the screen feels" -- Lots of data in tight rows, or spacious cards with breathing room?
+- "The overall vibe" -- Feels like a serious work tool, or a friendly personal app?
+- "How you interact with things" -- Drag things around? Edit right on the page? Or click to open a separate panel?
+
+For a "documentation site" project:
+- "What you see first" -- A big welcome section, or straight into the content?
+- "The personality" -- Precise and technical, or warm and approachable?
+- "How you find things" -- A big menu with everything visible, a simple top bar, or a sidebar?
+
+NOT generic: "UI layout", "Color scheme", "Typography choices" -- these are categories, not gray areas.
+
+**Map core design questions to gray areas.** Each of the 6 core design preferences should have a natural home in one of the generated gray areas:
+
+| Core Question | Natural Fit Examples |
+|---------------|---------------------|
+| Overall feel (professional/modern/warm/bold) | The overall vibe, Visual identity |
+| Color mood (warm/cool/neutral/bright) | The overall vibe, Visual identity |
+| Font style (clean modern/classic book/code-style) | How content reads, Reading experience |
+| How packed the screen feels (spacious/balanced/dense) | How packed the screen feels, Content density |
+| Dark or light (dark-default/toggle/light-only) | Can be its own area or fit under Look and feel |
+| Screen sizes (desktop-first/all-sizes/desktop-only) | Can be its own area or fit under Device strategy |
+
+Track which core questions are mapped to which gray areas.
+
+#### Step 2: Present Gray Areas for Selection
+
+Use AskUserQuestion with multiSelect: true:
+
+```
+- header: "Design Direction"
+- question: "Which design areas should we discuss for [stage name]?"
+- options: [3-5 project-specific gray areas, each with a short description of what questions it covers]
+```
+
+Do NOT include a "skip all" option. The user ran design to get design -- give them real choices. Core design questions embedded in unselected areas will be caught by the fallback round (Step 4).
+
+#### Step 3: Deep-Dive Each Selected Area
+
+For each selected area, in order:
+
+1. Announce the area: "Let's talk about [area]."
+
+2. Ask 3-4 questions using AskUserQuestion, each with 2-4 concrete options:
+   - Include the core design question(s) mapped to this area as structured AskUserQuestion calls
+   - Every question MUST include a "Let Claude decide" option
+   - For subjective/brand questions (visual style, color direction): recommend a specific option (label it "(Recommended)")
+   - For opinionated/technical questions (typography pairing, spacing rhythm, border radius): recommend "Let Claude decide" (label it "(Recommended)")
+   - For mixed questions (layout density, dark mode, responsive): recommend a specific option
+   - Each subsequent question informed by previous answers in this area
+   - After the core question(s), ask 1-2 project-specific follow-up questions for the gray area
+   - **Plain-language rule:** Describe what the user would see, not design terminology. Say "rounded friendly buttons vs sharp clean edges" not "border-radius values"
+
+3. After 3-4 questions for the area, offer: "More questions about [area], or move to next?"
+   - If "More questions": ask 2-3 more, then check again
+   - If "Next area": proceed to next selected area
+
+**Scope guardrail:** If the user suggests something outside the stage domain during discussion:
+```
+"[Feature] sounds like a new capability -- that belongs in its own stage.
+Let's focus on the design direction for [current stage]."
+```
+
+**Target up to {VISUAL_BUDGET} questions across all areas, where VISUAL_BUDGET = 15 - UX_QUESTIONS_ASKED.** If UX interview was skipped (UX_QUESTIONS_ASKED=0), target 8-15. The combined interview (UX + visual) should take 2-3 minutes, not 10.
+
+#### Step 4: Core Question Fallback
+
+After all selected gray areas are discussed, check which core design questions were NOT asked (because their containing gray area was deselected or no gray area naturally contained them).
+
+```
+CORE_QUESTIONS = [visual_style, color_direction, typography, layout_density, dark_mode, responsive]
+ASKED_QUESTIONS = [questions already embedded in gray area discussions]
+REMAINING = CORE_QUESTIONS - ASKED_QUESTIONS
+```
+
+If REMAINING is not empty, present: "A few more design essentials:"
+
+For each remaining core question, use AskUserQuestion with the standard options:
+
+- **Overall feel:** Professional and minimal, Clean and modern, Warm and inviting, Bold and expressive, Let Claude decide
+- **Color mood:** Warm tones (earthy, sunset), Cool tones (ocean, sky), Neutral (grays, black & white), Bright and colorful, Let Claude decide (Recommended)
+- **Font style:** Clean modern fonts (like most apps), Classic book-style fonts (like newspapers), Code-style fonts (like a terminal), A mix of styles, Let Claude decide (Recommended)
+- **How packed the screen feels:** Lots of breathing room, Balanced (not too sparse, not too tight), Information-dense (show as much as possible), Let Claude decide (Recommended)
+- **Dark or light:** Dark background by default, Light with a dark mode toggle, Light only, Let Claude decide
+- **Screen sizes:** Starts on desktop, adapts to phones, Works on all screen sizes equally, Desktop only, Let Claude decide
+
+#### Step 5: Pexels API Key Collection
+
+After all design questions are answered, collect the Pexels API key as part of the same flow.
+
+```bash
+PEXELS_KEY=$(cat .renn/secrets.json 2>/dev/null | grep -o '"pexels_api_key"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "")
+```
+
+If key already exists in secrets.json: read silently, no prompt. Display: "Pexels key found."
+
+If empty or missing, present as AskUserQuestion:
+
+```
+- header: "One last thing"
+- question: "Pexels API key enables real stock images in prototypes. Get a free key at https://www.pexels.com/api/"
+- options:
+  - "Paste my key" -- I have a key ready
+  - "Skip" -- Use placeholder images instead
+```
+
+If user selects "Paste my key", prompt for the key value. Then:
+1. Read existing `.renn/secrets.json` content (if file exists) to preserve other fields
+2. Merge `{"pexels_api_key": "{user_input}"}` into the existing JSON object
+3. Write merged JSON back to `.renn/secrets.json`
+4. Set `PEXELS_KEY` to the provided value
+5. Display: "Pexels API key saved."
+
+If user selects "Skip":
+1. Set `PEXELS_KEY="NOT_AVAILABLE"`
+2. Display: "Using placeholder images."
+3. Do NOT create or modify secrets.json
+
+Ensure `.renn/secrets.json` is gitignored:
+
+```bash
+grep -q "secrets.json" .gitignore 2>/dev/null || echo ".renn/secrets.json" >> .gitignore
+```
+
+#### Step 6: Compile Design Preferences
+
+Compile all collected answers into a `DESIGN_PREFERENCES` variable using this format:
+
+```xml
+<design_preferences>
+
+## Design Direction
+
+### Visual Style
+Pick: {user's choice OR "Designer's choice"}
+Context: {any elaboration from follow-up questions}
+
+### Color Direction
+Pick: {user's choice OR "Designer's choice"}
+Context: {any elaboration}
+
+### Typography
+Pick: {user's choice OR "Designer's choice"}
+Context: {any elaboration}
+
+### Layout
+Pick: {user's choice OR "Designer's choice"}
+Context: {any elaboration}
+
+### Dark Mode
+Pick: {user's choice OR "Designer's choice"}
+
+### Responsive
+Pick: {user's choice OR "Designer's choice"}
+
+## Project-Specific Insights
+
+### [Gray Area 1 that was discussed]
+- {Decision or preference captured}
+- {Another decision}
+
+### [Gray Area 2 that was discussed]
+- {Decision or preference captured}
+
+## Designer Autonomy
+
+The following aspects are marked as "Designer's choice" -- you have creative autonomy:
+- {list of items where user picked "Let Claude decide"}
+
+For these items, make opinionated choices that serve the project's domain and stage goals. Explain your reasoning in the design return.
+
+</design_preferences>
+```
+
+Store in `DESIGN_PREFERENCES` for use in the Phase 1 spawn template.
+
+Display: "Design preferences captured. Proceeding to design system creation..."
+
+### Initialize Counters
+
+```
+auto_revision_count = 0
+user_revision_count = 0
+```
+
+### Two-Phase Design Orchestration
+
+The design workflow runs in two phases with an approval gate between them. Each phase has its own designer spawn, reviewer spawn, auto-revision loop, approval gate, and user revision loop.
+
+- **Full mode:** Phase 1 (stylekit) then Phase 2 (screens)
+- **screens_only mode:** Phase 2 only (stylekit already approved from a prior stage)
+
+---
+
+### Phase 1: Design System (ONLY when DESIGN_MODE="full")
+
+**If `DESIGN_MODE="screens_only"`: Skip Phase 1 entirely. Jump to Phase 2.**
+
+#### Phase 1 -- Assemble Designer Context and Spawn
+
+11 context variables (plus `phase`):
+
+| Variable | Source |
+|----------|--------|
+| `design_mode` | DESIGN_MODE ("full" or "translate") |
+| `phase` | "stylekit" |
+| `stage_name` | parse_args |
+| `stage_goal` | track.md stage details |
+| `research_content` | `${STAGE_DIR}/research.md` content |
+| `intel_content` | INTEL_CONTENT (loaded in ensure_stage_directory) |
+| `design_preferences` | DESIGN_PREFERENCES (compiled from design interview Step 6) |
+| `pexels_key` | Pexels API key check result |
+| `stage_dir` | STAGE_DIR path |
+| `translation_context` | TRANSLATION_CONTEXT (DESIGN.md content, only when DESIGN_MODE="translate") |
+| `translation_strategy` | TRANSLATE_STRATEGY ("absorb" or "extend", only when DESIGN_MODE="translate") |
+| `design_extension_preferences` | DESIGN_EXTENSION_PREFERENCES (only when TRANSLATE_STRATEGY="extend") |
+| `ux_brief` | UX_BRIEF (from ux_synthesis step, if non-empty) |
+| `project_name` | PROJECT_NAME (from brief.md heading) |
+| `platform` | PLATFORM (from brief.md Context section) |
+| `viewport_raw` | VIEWPORT_RAW (from brief.md Context section) |
+
+Note: `stylekit_content` and `component_names` are NOT passed in Phase 1 (they don't exist yet).
+
+Phase 1 designer spawn template:
+
+```
+<design_context>
+
+**Project Name:** {PROJECT_NAME}
+**Mode:** {DESIGN_MODE}
+**Phase:** stylekit
+
+{IF PROJECT_LEVEL=true:}
+**Scope:** All UI stages
+**UI Stages:**
+{for each stage in UI_STAGES: "- Stage {N}: {name} -- {goal}"}
+{END IF}
+
+{IF PROJECT_LEVEL=false:}
+**Stage:** {stage_name}
+**Goal:** {stage_goal}
+{END IF}
+
+{DESIGN_PREFERENCES}
+
+{IF UX_BRIEF is non-empty:}
+
+**UX Brief (from UX research + interview):**
+{UX_BRIEF}
+
+This ux_brief provides concrete UX direction based on research and user interview answers.
+Use it to inform spacing/density decisions, component selection, and interaction patterns.
+The ux_brief is INFORMATIONAL -- it supplements design preferences but does not override them.
+
+{END IF}
+
+{IF PLATFORM is not "web" AND VIEWPORT_RAW is non-empty:}
+
+**Viewport Context (from brief.md):**
+**Platform:** {PLATFORM}
+**Target Viewport:** {VIEWPORT_RAW}
+
+Use this viewport metadata to populate the stylekit.yaml viewport section (step 3b) and apply viewport wrapping to screen prototypes (step 2b). Parse the target viewport string to extract width, height, frame ID, and other viewport schema fields.
+
+{END IF}
+
+{IF DESIGN_MODE == "translate":}
+
+**Translation Mode:**
+**Strategy:** {TRANSLATE_STRATEGY}
+
+<translation_context>
+{TRANSLATION_CONTEXT}
+</translation_context>
+
+{IF TRANSLATE_STRATEGY == "extend":}
+{DESIGN_EXTENSION_PREFERENCES}
+{END IF}
+
+**Translation Instructions:**
+- Extract concrete values from the existing design into the three-layer token architecture
+- Map colors, fonts, spacing, shadows, border radii to proper primitive/semantic/component tokens
+- For absorb: reproduce existing design faithfully, fill gaps with sensible defaults based on the extracted palette
+- For extend: reproduce existing design, then enhance using the extension preferences above
+- SKIP the anti-generic checklist (existing design is intentional, not AI-generated)
+- Generate stylekit-preview.html for user verification: "Does this represent your existing design?"
+
+{END IF}
+
+**Research:**
+{research_content}
+
+**Intel (raw -- extract design-relevant decisions yourself):**
+{intel_content}
+
+**Token Schema Reference:** Follow the 3-layer architecture (primitive, semantic, component) from the design token specification. W3C DTCG $type/$value structure. Namespace mapping: primitive.color.* -> --color-*, primitive.typography.family.* -> --font-*, primitive.typography.size.* -> --text-*, etc. All :root values resolved to concrete CSS (no var() references inside :root block). Stylekit.css uses plain :root {} custom properties, not Tailwind v4 @theme syntax. HTML boilerplate uses Tailwind v3 CDN with inline tailwind.config mapping tokens to theme extensions.
+**Component Schema Reference:** Follow the component inventory format: required fields are name, description, category, properties, tokens, states, responsive, accessibility, preview. State vocabulary fixed at 8: default, hover, active, focus, disabled, loading, error, empty. Token-driven preview using semantic Tailwind classes.
+
+**Pexels API Key:** {pexels_key}
+
+**Output Directories:**
+- Stylekit: .renn/design/
+- Components: .renn/design/components/
+- Preview: .renn/design/stylekit-preview.html
+
+</design_context>
+```
+
+For Phase 1 revisions, append a `<revision_context>` block:
+
+```
+<revision_context>
+
+**Revision:** {N} of 3
+**Phase:** stylekit
+**Source:** {reviewer | user}
+**Feedback:**
+{feedback_text}
+
+**Current artifacts on disk:**
+{list of existing artifact paths}
+
+Revise the design system based on the feedback above. When changing tokens, cascade changes to all affected components and the preview (see Cascading Token Revisions rule). Overwrite files in place (git tracks previous versions).
+Return ## DESIGN REVISION (not ## DESIGN COMPLETE) to signal this is a revision.
+
+</revision_context>
+```
+
+Display banner before spawning:
+
+**If PROJECT_LEVEL=true:**
+
+```
+RENN > PROJECT DESIGN -- PHASE 1: DESIGN SYSTEM
+{IF DESIGN_MODE == "translate":}
+Spawning designer (mode: translate, strategy: {TRANSLATE_STRATEGY}, phase: stylekit)...
+{ELSE:}
+Spawning designer (mode: full, phase: stylekit)...
+{END IF}
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+RENN > DESIGNING STAGE {X} -- PHASE 1: DESIGN SYSTEM
+{IF DESIGN_MODE == "translate":}
+Spawning designer (mode: translate, strategy: {TRANSLATE_STRATEGY}, phase: stylekit)...
+{ELSE:}
+Spawning designer (mode: full, phase: stylekit)...
+{END IF}
+```
+
+Spawn:
+
+**If PROJECT_LEVEL=true:**
+
+```
+Task(
+  prompt=designer_prompt,
+  subagent_type="renn-designer",
+  model="{designer_model}",
+  description="Design Project - Phase 1 (stylekit)"
+)
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+Task(
+  prompt=designer_prompt,
+  subagent_type="renn-designer",
+  model="{designer_model}",
+  description="Design Stage {stage} - Phase 1 (stylekit)"
+)
+```
+
+Parse designer return: `## DESIGN COMPLETE` or `## DESIGN REVISION`. Verify `**Phase:** stylekit` in the return.
+
+#### Phase 1 -- Spawn Reviewer
+
+Reviewer spawn template:
+
+```
+<review_context>
+
+**Mode:** full
+**Phase:** stylekit
+**Designer Output:**
+{designer_return}
+
+**Artifact Paths:**
+{artifact_paths}
+
+Review stylekit, components, and preview for spec compliance, anti-generic aesthetics, and overall quality.
+Phase scope: token structure, component YAML, preview HTML, full anti-generic checklist, component consistency.
+Return REVIEW PASSED or ISSUES FOUND with actionable feedback.
+
+</review_context>
+```
+
+**If PROJECT_LEVEL=true:**
+
+```
+Task(
+  prompt=reviewer_prompt,
+  subagent_type="renn-design-reviewer",
+  model="{reviewer_model}",
+  description="Review design Phase 1 (stylekit) for project"
+)
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+Task(
+  prompt=reviewer_prompt,
+  subagent_type="renn-design-reviewer",
+  model="{reviewer_model}",
+  description="Review design Phase 1 (stylekit) for Stage {stage}"
+)
+```
+
+#### Phase 1 -- Auto-Revision Loop
+
+Same logic as the standard auto-revision pattern, using the shared `auto_revision_count`:
+
+If `## ISSUES FOUND`:
+1. Increment `auto_revision_count`
+2. If `auto_revision_count <= 2`:
+   - Display: "Reviewer found issues. Auto-revising... (attempt {auto_revision_count}/2)"
+   - Re-spawn designer with Phase 1 context + revision_context (source: "reviewer", feedback: reviewer's issue list)
+   - After designer returns: re-spawn reviewer (phase: stylekit)
+   - Loop back to check reviewer return
+3. If `auto_revision_count > 2`:
+   - Display: "Auto-revision limit reached. Escalating to user."
+   - Present Phase 1 escalation (see Phase 1 Escalation below)
+
+If `## REVIEW PASSED`:
+- Reset `auto_revision_count = 0`
+- Proceed to Phase 1 Approval Gate
+
+#### Phase 1 -- Approval Gate
+
+**Step 1 -- Auto-open preview in browser:**
+
+Build the file list for Phase 1: `.renn/design/stylekit-preview.html` ONLY.
+
+```bash
+# EXECUTE THIS NOW -- open Phase 1 preview before showing gate
+GATE_FILES=".renn/design/stylekit-preview.html"
+for file in $GATE_FILES; do
+  if [[ -f "$file" ]]; then
+    if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" ]]; then
+      start "" "$file"
+    elif [[ "$OSTYPE" == "darwin"* ]]; then
+      open "$file"
+    elif command -v xdg-open &>/dev/null; then
+      xdg-open "$file" &>/dev/null &
+    elif command -v cmd.exe &>/dev/null; then
+      cmd.exe /c start "" "$file"
+    fi
+    sleep 0.5
+  fi
+done
+```
+
+**Step 2 -- Present checkpoint:human-verify:**
+
+**If PROJECT_LEVEL=true:**
+
+```
+what-built: "Design system for project"
+how-to-verify:
+  1. Review design system preview in browser (auto-opened):
+     - .renn/design/stylekit-preview.html (colors, typography, spacing, components)
+  2. Check that color palette matches your brand vision
+  3. Verify typography feels right for your project
+  4. Review component styling (buttons, cards, inputs, etc.)
+  Note: This project-level design system will be used across all UI stages.
+resume-signal: Type "approved" or describe what to change (e.g., "make primary color darker", "switch to a serif font")
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+what-built: "Design system for Stage {N}: {stage_name}"
+how-to-verify:
+  1. Review design system preview in browser (auto-opened):
+     - .renn/design/stylekit-preview.html (colors, typography, spacing, components)
+  2. Check that color palette matches your brand vision
+  3. Verify typography feels right for your project
+  4. Review component styling (buttons, cards, inputs, etc.)
+  Note: Screen layouts are created in the next phase after you approve this design system.
+resume-signal: Type "approved" or describe what to change (e.g., "make primary color darker", "switch to a serif font")
+```
+
+#### Phase 1 -- User Revision Loop
+
+If user types "approved": Proceed to Phase 1 -> Phase 2 transition.
+
+If user provides feedback:
+1. Increment `user_revision_count`
+2. If `user_revision_count <= 3`:
+   - Re-spawn designer with Phase 1 context + revision_context (source: "user", feedback: user's text). Note: revision_context includes the cascade instruction.
+   - After designer returns: re-spawn reviewer (phase: stylekit)
+   - If reviewer passes: present updated Phase 1 gate
+   - If reviewer fails: enter Phase 1 auto-revision loop, then present to user
+3. If `user_revision_count > 3`: Present Phase 1 escalation
+
+#### Phase 1 -- Escalation
+
+Present `checkpoint:decision`:
+
+**If PROJECT_LEVEL=true:**
+
+```
+Design system has reached the revision limit.
+
+Current state: {summary of latest designer output}
+{IF reviewer issues exist:} Reviewer concerns: {summary of latest issues}
+
+Options:
+  Accept - Use current design system as-is
+  Restart - Start over with a completely new design direction
+  Skip - Skip design for this project (no design system will be created)
+
+Select: accept, restart, or skip
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+Design system has reached the revision limit.
+
+Current state: {summary of latest designer output}
+{IF reviewer issues exist:} Reviewer concerns: {summary of latest issues}
+
+Options:
+  Accept - Use current design system as-is (proceed to screen design)
+  Restart - Start over with a completely new design direction
+  Skip - Skip ALL design for this stage (no screens will be created)
+
+Select: accept, restart, or skip
+```
+
+Behavior:
+- `accept`: Proceed to Phase 2 with current stylekit (treated as approved).
+- `restart`: Delete `.renn/design/` contents (stylekit, CSS, components, preview). Reset both counters to 0. Re-run Phase 1 from designer spawn.
+- `skip`: Delete `.renn/design/` contents. Set `HAS_DESIGN=false`. Skip Phase 2. Continue to present_final_status.
+
+**CRITICAL:** Phase 1 skip aborts BOTH phases. There is no path where Phase 1 is skipped but Phase 2 runs.
+
+#### Phase 1 -- Commit Design Artifacts
+
+**After Phase 1 approval (before Phase 2 transition):**
+
+```bash
+if [ "$COMMIT_PLANNING_DOCS" = "true" ]; then
+  git add .renn/design/stylekit.yaml
+  git add .renn/design/stylekit.css
+  git add .renn/design/stylekit-preview.html
+  git add .renn/design/components/
+  git commit -m "docs(${COMMIT_PREFIX}): approve Phase 1 design system
+
+Phase 1 (stylekit) approved for ${COMMIT_MSG_SCOPE}
+- Design tokens: stylekit.yaml + stylekit.css
+- Component inventory committed
+- Preview: stylekit-preview.html"
+else
+  echo "Skipping Phase 1 design commit (commit_docs: false)"
+fi
+```
+
+#### Phase 1 -- Stop for design-system command
+
+**If `--phase-1-only` flag is set:**
+- Skip Phase 2 entirely
+- Skip implementation guide generation
+- Route to the command's `<offer_next>` section
+- STOP
+
+**Otherwise:** Continue to Phase 1 -> Phase 2 transition as normal.
+
+#### Phase 1 -> Phase 2 Transition
+
+After Phase 1 approval (or accept-as-is):
+
+1. Reset counters for Phase 2:
+   ```
+   auto_revision_count = 0
+   user_revision_count = 0
+   ```
+
+2. Store Phase 1 artifacts for Phase 2 context:
+   ```
+   APPROVED_STYLEKIT_PATH=".renn/design/stylekit.yaml"
+   APPROVED_COMPONENT_NAMES=$(ls .renn/design/components/ 2>/dev/null)
+   ```
+
+3. Proceed to Phase 2.
+
+---
+
+### Phase 2: Screen Prototypes (runs for BOTH full and screens_only modes)
+
+#### Phase 2 -- Assemble Designer Context and Spawn
+
+| Variable | Source |
+|----------|--------|
+| `design_mode` | Original mode determination result (full or screens_only) |
+| `phase` | "screens" |
+| `stage_name` | parse_args |
+| `stage_goal` | track.md stage details |
+| `research_content` | `${STAGE_DIR}/research.md` content |
+| `intel_content` | INTEL_CONTENT |
+| `stylekit_content` | Content of `.renn/design/stylekit.yaml` (read now -- locked, do not modify) |
+| `component_names` | `ls .renn/design/components/` directory listing |
+| `pexels_key` | Pexels API key check result |
+| `stage_dir` | STAGE_DIR path |
+| `existing_screens` | `ls .renn/design/screens/*.yaml 2>/dev/null` with name + description for each |
+| `ux_brief` | UX_BRIEF (from ux_synthesis step, if non-empty) |
+| `project_name` | PROJECT_NAME (from brief.md heading) |
+
+**Assemble existing screen context:**
+
+```bash
+EXISTING_SCREENS=""
+for spec in .renn/design/screens/*.yaml; do
+  [ -f "$spec" ] || continue
+  screen_name=$(grep -m1 "^screen:" "$spec" | sed 's/screen: //')
+  description=$(grep -m1 "^description:" "$spec" | sed 's/description: //')
+  EXISTING_SCREENS="${EXISTING_SCREENS}\n- ${screen_name}: ${description}"
+done
+```
+
+If `EXISTING_SCREENS` is empty, the designer creates all screens as new. If populated, the designer reads each relevant existing screen before deciding whether to create new or update.
+
+Phase 2 designer spawn template:
+
+```
+<design_context>
+
+**Project Name:** {PROJECT_NAME}
+**Mode:** {design_mode}
+**Phase:** screens
+
+{IF PROJECT_LEVEL=true:}
+**Scope:** All UI stages
+**UI Stages:**
+{for each stage in UI_STAGES: "- Stage {N}: {name} -- {goal}"}
+{END IF}
+
+{IF PROJECT_LEVEL=false:}
+**Stage:** {stage_name}
+**Goal:** {stage_goal}
+{END IF}
+
+**Research:**
+{research_content}
+
+**Intel (raw -- extract design-relevant decisions yourself):**
+{intel_content}
+
+{IF UX_BRIEF is non-empty:}
+
+**UX Brief (from UX research + interview):**
+{UX_BRIEF}
+
+This ux_brief provides concrete UX direction. Reference it for flow design,
+component density, and interaction patterns when creating screen layouts.
+The ux_brief is INFORMATIONAL -- it supplements intel decisions.
+
+{END IF}
+
+**Approved Stylekit:** (locked -- do not modify)
+{stylekit_content}
+
+**Available Components:**
+{component_names}
+
+**Pexels API Key:** {pexels_key}
+
+**Existing Screens** (at .renn/design/screens/ -- read before creating):
+{EXISTING_SCREENS}
+
+**Output Directory:**
+- Screen specs and prototypes: .renn/design/screens/
+
+</design_context>
+```
+
+For Phase 2 revisions, append:
+
+```
+<revision_context>
+
+**Revision:** {N} of 3
+**Phase:** screens
+**Source:** {reviewer | user}
+**Feedback:**
+{feedback_text}
+
+**Current artifacts on disk:**
+{list of existing artifact paths}
+
+Revise screen prototypes based on the feedback above. The design system (stylekit, components) is locked -- do not modify tokens or existing components. Overwrite prototype files in place (git tracks previous versions).
+Return ## DESIGN REVISION (not ## DESIGN COMPLETE) to signal this is a revision.
+
+</revision_context>
+```
+
+Display banner:
+
+**If PROJECT_LEVEL=true:**
+
+```
+RENN > PROJECT DESIGN -- PHASE 2: SCREEN PROTOTYPES
+
+Spawning designer (mode: {design_mode}, phase: screens)...
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+RENN > DESIGNING STAGE {X} -- PHASE 2: SCREEN PROTOTYPES
+
+Spawning designer (mode: {design_mode}, phase: screens)...
+```
+
+Spawn:
+
+**If PROJECT_LEVEL=true:**
+
+```
+Task(
+  prompt=designer_prompt,
+  subagent_type="renn-designer",
+  model="{designer_model}",
+  description="Design Project - Phase 2 (screens)"
+)
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+Task(
+  prompt=designer_prompt,
+  subagent_type="renn-designer",
+  model="{designer_model}",
+  description="Design Stage {stage} - Phase 2 (screens)"
+)
+```
+
+Parse designer return: `## DESIGN COMPLETE` or `## DESIGN REVISION`. Verify `**Phase:** screens` in the return.
+
+#### Phase 2 -- Spawn Reviewer
+
+```
+<review_context>
+
+**Mode:** {design_mode}
+**Phase:** screens
+**Designer Output:**
+{designer_return}
+
+**Artifact Paths:**
+{artifact_paths}
+
+Review screen specs and prototypes for spec compliance and overall quality.
+Phase scope: screen spec YAML, screen prototype HTML, layout coherence, responsive overrides, images. Skip stylekit/component checks (already approved).
+Return REVIEW PASSED or ISSUES FOUND with actionable feedback.
+
+</review_context>
+```
+
+**If PROJECT_LEVEL=true:**
+
+```
+Task(
+  prompt=reviewer_prompt,
+  subagent_type="renn-design-reviewer",
+  model="{reviewer_model}",
+  description="Review design Phase 2 (screens) for project"
+)
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+Task(
+  prompt=reviewer_prompt,
+  subagent_type="renn-design-reviewer",
+  model="{reviewer_model}",
+  description="Review design Phase 2 (screens) for Stage {stage}"
+)
+```
+
+#### Phase 2 -- Auto-Revision Loop
+
+Same logic as Phase 1, using the reset `auto_revision_count`:
+
+If `## ISSUES FOUND`:
+1. Increment `auto_revision_count`
+2. If `auto_revision_count <= 2`:
+   - Display: "Reviewer found issues. Auto-revising... (attempt {auto_revision_count}/2)"
+   - Re-spawn designer with Phase 2 context + revision_context (source: "reviewer", feedback: reviewer's issue list)
+   - After designer returns: re-spawn reviewer (phase: screens)
+   - Loop back to check reviewer return
+3. If `auto_revision_count > 2`:
+   - Display: "Auto-revision limit reached. Escalating to user."
+   - Present Phase 2 escalation (see Phase 2 Escalation below)
+
+If `## REVIEW PASSED`:
+- Reset `auto_revision_count = 0`
+- Proceed to Phase 2 Approval Gate
+
+#### Phase 2 -- Approval Gate
+
+**Step 1 -- Auto-open prototypes in browser:**
+
+Build the file list for Phase 2: `.renn/design/screens/*.html` ONLY (screen prototypes created or modified this session, not stylekit-preview.html).
+
+```bash
+# EXECUTE THIS NOW -- open Phase 2 prototypes before showing gate
+# Use the designer's structured return to get only new/modified screen files
+# The designer return lists artifacts with [NEW] and [MODIFIED] markers
+# Parse the artifact list from the designer's last return to get specific files
+GATE_FILES=""
+for f in .renn/design/screens/*.html; do
+  [ -f "$f" ] || continue
+  # Only include screens that the designer created or modified this session
+  # The designer's structured return lists specific files -- parse them
+  GATE_FILES="$GATE_FILES $f"
+done
+# NOTE: The orchestrator should filter GATE_FILES using the artifact paths
+# from the designer's ## DESIGN COMPLETE return (new + modified only).
+# If the designer return is not parseable, fall back to opening all screens
+# in .renn/design/screens/ (user can identify which are relevant).
+for file in $GATE_FILES; do
+  if [[ -f "$file" ]]; then
+    if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" ]]; then
+      start "" "$file"
+    elif [[ "$OSTYPE" == "darwin"* ]]; then
+      open "$file"
+    elif command -v xdg-open &>/dev/null; then
+      xdg-open "$file" &>/dev/null &
+    elif command -v cmd.exe &>/dev/null; then
+      cmd.exe /c start "" "$file"
+    fi
+    sleep 0.5
+  fi
+done
+```
+
+**Step 2 -- Present checkpoint:human-verify:**
+
+**If PROJECT_LEVEL=true:**
+
+```
+what-built: "Screen prototypes for project"
+how-to-verify:
+  1. Review screen prototypes in browser (auto-opened):
+     {For each [NEW] screen from designer return:}
+     - .renn/design/screens/{screen-name}.html [NEW] -- {description}
+     {For each [MODIFIED] screen from designer return:}
+     - .renn/design/screens/{screen-name}.html [MODIFIED] -- {modification summary}
+  2. Check that layouts match your vision for each screen
+  3. Verify components are used consistently across screens
+  4. Review responsive behavior if applicable
+  Note: The design system (colors, fonts, spacing) was approved in the previous phase. Screen feedback should be about layout and content, not colors/fonts.
+resume-signal: Type "approved" or describe what to change
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+what-built: "Screen prototypes for Stage {N}: {stage_name}"
+how-to-verify:
+  1. Review screen prototypes in browser (auto-opened):
+     {For each [NEW] screen from designer return:}
+     - .renn/design/screens/{screen-name}.html [NEW] -- {description}
+     {For each [MODIFIED] screen from designer return:}
+     - .renn/design/screens/{screen-name}.html [MODIFIED] -- {modification summary}
+  2. Check that layouts match your vision for each screen
+  3. Verify components are used consistently across screens
+  4. Review responsive behavior if applicable
+  Note: The design system (colors, fonts, spacing) was approved in the previous phase. Screen feedback should be about layout and content, not colors/fonts.
+  {IF DESIGN_MODE is screens_only:}
+  Note: Using existing design system from a prior stage. If you want to change the visual identity, restart with a restyle.
+resume-signal: Type "approved" or describe what to change
+```
+
+#### Phase 2 -- User Revision Loop
+
+If user types "approved": Store design output. Continue to generate_implementation_guide.
+
+If user provides feedback:
+1. Increment `user_revision_count`
+2. If `user_revision_count <= 3`:
+   - Re-spawn designer with Phase 2 context + revision_context (source: "user", feedback: user's text)
+   - After designer returns: re-spawn reviewer (phase: screens)
+   - If reviewer passes: present updated Phase 2 gate
+   - If reviewer fails: enter Phase 2 auto-revision loop, then present to user
+3. If `user_revision_count > 3`: Present Phase 2 escalation
+
+#### Phase 2 -- Escalation
+
+Present `checkpoint:decision`:
+
+**If PROJECT_LEVEL=true:**
+
+```
+Screen prototypes have reached the revision limit.
+
+Current state: {summary of latest designer output}
+{IF reviewer issues exist:} Reviewer concerns: {summary of latest issues}
+
+Options:
+  Accept - Use current screen prototypes as-is (proceed to implementation guide)
+  Restart - Start over with new screen layouts (design system stays locked)
+  Skip - Skip screen design (stylekit exists but no screen specs for this project)
+
+Select: accept, restart, or skip
+```
+
+**If PROJECT_LEVEL=false:**
+
+```
+Screen prototypes have reached the revision limit.
+
+Current state: {summary of latest designer output}
+{IF reviewer issues exist:} Reviewer concerns: {summary of latest issues}
+
+Options:
+  Accept - Use current screen prototypes as-is (proceed to implementation guide)
+  Restart - Start over with new screen layouts (design system stays locked)
+  Skip - Skip screen design (stylekit exists but no screen specs for this stage)
+
+Select: accept, restart, or skip
+```
+
+Behavior:
+- `accept`: Store current screen artifacts as approved. Continue to Store Design Output.
+- `restart`: Revert current session's screen changes only (NOT all screens in .renn/design/screens/):
+  - For screens marked [NEW] in the designer's return: delete the .yaml and .html files from .renn/design/screens/
+  - For screens marked [MODIFIED] in the designer's return: `git checkout .renn/design/screens/{screen-name}.yaml .renn/design/screens/{screen-name}.html` to restore pre-session state
+  - The stylekit and screens from prior stages are untouched.
+  Reset Phase 2 counters to 0. Re-run Phase 2 from designer spawn.
+- `skip`: Revert current session's screen changes (same scoped approach as restart). Stylekit remains. Continue to Store Design Output (HAS_DESIGN still true since stylekit exists, but no new/modified screen specs for this stage).
+
+---
+
+#### Phase 2 -- Commit Design Artifacts
+
+**After Phase 2 approval (before Store Design Output):**
+
+```bash
+if [ "$COMMIT_PLANNING_DOCS" = "true" ]; then
+  git add .renn/design/screens/
+  git commit -m "docs(${COMMIT_PREFIX}): approve Phase 2 screen prototypes
+
+Phase 2 (screens) approved for ${COMMIT_MSG_SCOPE}
+- Screen specs and prototypes committed"
+else
+  echo "Skipping Phase 2 design commit (commit_docs: false)"
+fi
+```
+
+### Store Design Output
+
+After Phase 2 approval (or accept-as-is escalation), store the design output paths:
+
+```
+# Screen specs are now at the global location
+# Use the designer's return to know which screens belong to this stage
+DESIGN_SCREEN_SPECS=$(ls .renn/design/screens/*.yaml 2>/dev/null)
+DESIGN_STYLEKIT_PATH=".renn/design/stylekit.yaml"
+HAS_DESIGN=true
+```
+
+If Phase 2 was skipped but Phase 1 completed (Phase 2 skip escalation):
+
+```
+DESIGN_SCREEN_SPECS=""
+DESIGN_STYLEKIT_PATH=".renn/design/stylekit.yaml"
+HAS_DESIGN=true
+```
+
+</step>
+
+<step name="generate_implementation_guide">
+**Trigger:** `HAS_DESIGN=true` (design phase completed and approved).
+
+**Skip if:** `.renn/design/implementation-guide.md` already exists AND no design artifacts have changed since last generation:
+
+```bash
+if [ "$HAS_DESIGN" != "true" ]; then
+  # No design -- skip entirely
+  :
+elif [ -f ".renn/design/implementation-guide.md" ]; then
+  # Guide exists -- check if design artifacts changed since guide was generated
+  GUIDE_MTIME=$(stat -c %Y .renn/design/implementation-guide.md 2>/dev/null || stat -f %m .renn/design/implementation-guide.md 2>/dev/null)
+  DESIGN_CHANGED=false
+  for f in .renn/design/screens/*.html .renn/design/stylekit.yaml .renn/design/stylekit.css; do
+    [ -f "$f" ] || continue
+    FILE_MTIME=$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f" 2>/dev/null)
+    if [ "$FILE_MTIME" -gt "$GUIDE_MTIME" ] 2>/dev/null; then
+      DESIGN_CHANGED=true
+      break
+    fi
+  done
+  if [ "$DESIGN_CHANGED" = "false" ]; then
+    echo "Implementation guide up to date. Skipping regeneration."
+    # Skip to present_final_status
+  fi
+fi
+```
+
+If skip conditions are not met, proceed with generation:
+
+### 1. Detect CSS Framework
+
+```bash
+# Check for Tailwind
+TAILWIND_VERSION=""
+if grep -q '"tailwindcss"' package.json 2>/dev/null; then
+  TAILWIND_VERSION=$(grep '"tailwindcss"' package.json | grep -oE '[0-9]+\.[0-9]+')
+fi
+
+# Determine CSS framework
+CSS_FRAMEWORK="unknown"
+if [ -n "$TAILWIND_VERSION" ]; then
+  if echo "$TAILWIND_VERSION" | grep -qE '^4\.'; then
+    CSS_FRAMEWORK="tailwind-v4"
+  else
+    CSS_FRAMEWORK="tailwind-v3"
+  fi
+elif grep -q '"styled-components"' package.json 2>/dev/null; then
+  CSS_FRAMEWORK="styled-components"
+elif ls src/**/*.module.css 2>/dev/null | head -1; then
+  CSS_FRAMEWORK="css-modules"
+else
+  CSS_FRAMEWORK="vanilla-css"
+fi
+
+echo "Detected CSS framework: $CSS_FRAMEWORK"
+```
+
+### 2. Read Prototype HTML File List
+
+```bash
+PROTOTYPE_FILES=$(ls .renn/design/screens/*.html 2>/dev/null)
+STYLEKIT_YAML=".renn/design/stylekit.yaml"
+STYLEKIT_CSS=".renn/design/stylekit.css"
+```
+
+### 3. Spawn Implementation Guide Generator
+
+Display:
+```
+RENN > GENERATING IMPLEMENTATION GUIDE
+
+Detected CSS framework: {CSS_FRAMEWORK}
+Spawning guide generator...
+```
+
+Spawn a focused Task call (uses designer_model tier -- no new agent needed):
+
+```
+Task(
+  prompt="You are generating a design implementation guide that bridges HTML prototypes (Tailwind v3 CDN) to the project's actual CSS framework.\n\n" +
+    "<guide_context>\n" +
+    "**Project CSS Framework:** " + CSS_FRAMEWORK + "\n" +
+    "**Stylekit YAML:** Read @.renn/design/stylekit.yaml\n" +
+    "**Stylekit CSS:** Read @.renn/design/stylekit.css\n" +
+    "**HTML Prototypes:** Read each file in .renn/design/screens/*.html\n\n" +
+    "Generate .renn/design/implementation-guide.md with these sections (5 required + 1 conditional):\n\n" +
+    "## Framework Detection\n" +
+    "- CSS framework: {detected}\n" +
+    "- Version: {detected}\n" +
+    "- Configuration approach: {e.g., 'Tailwind v4 CSS-first config' or 'CSS custom properties in :root'}\n\n" +
+    "## Token System Translation\n" +
+    "- How to implement stylekit.yaml tokens in the project's framework\n" +
+    "- Exact file path and syntax for the project's CSS system\n" +
+    "- Token namespace mapping (stylekit token names -> project CSS custom properties or framework equivalents)\n" +
+    "- For vanilla CSS: map to CSS custom properties in :root {} (stylekit.css is directly usable)\n" +
+    "- For Tailwind v3: map to tailwind.config theme extensions\n" +
+    "- For Tailwind v4: map to CSS-first @theme declarations in the project's CSS entry point\n" +
+    "- For CSS Modules: map to shared CSS custom properties imported in each module\n" +
+    "- For styled-components: map to a theme object with token values\n\n" +
+    "## Icon System\n" +
+    "- Icon library used in prototypes: {detect from HTML -- typically Material Symbols Rounded}\n" +
+    "- npm install command for the project\n" +
+    "- Import pattern for the project's framework\n" +
+    "- Usage syntax (component vs font vs SVG)\n\n" +
+    "## Animation Patterns\n" +
+    "- List each @keyframes animation found in prototypes and stylekit.css\n" +
+    "- Where to define them in the project (globals.css, tailwind config, CSS module)\n" +
+    "- How to reference them (utility class, CSS class name, animation property)\n\n" +
+    "## Component Class Mapping\n" +
+    "- For each screen prototype: list key visual sections\n" +
+    "- For each section: the Tailwind v3 CDN classes used and their project-framework equivalent\n" +
+    "- Focus on classes that DIFFER between v3 CDN and the project framework\n" +
+    "- Skip structural classes (flex, grid, items-center) that are identical across frameworks\n\n" +
+    "## Viewport Translation (ONLY if stylekit.yaml has a viewport section)\n" +
+    "- If NO viewport section exists in stylekit.yaml: OMIT this section entirely\n" +
+    "- If viewport section exists:\n" +
+    "  - Target viewport type and dimensions from stylekit.yaml\n" +
+    "  - How to constrain the app's root layout to viewport dimensions in the project's framework\n" +
+    "  - For React Native/Flutter: map viewport dimensions to root container constraints\n" +
+    "  - For web targeting mobile: meta viewport tag, CSS max-width on app container, media queries\n" +
+    "  - For wearable: circular clip-path or border-radius constraints, safe area considerations\n" +
+    "  - Device-specific safe areas (notch, home indicator, status bar) and how to handle them\n" +
+    "  - RTL handling if direction is rtl (CSS logical properties, framework RTL support)\n\n" +
+    "**Target:** 100-250 lines (longer if viewport section included). Summary document, not full prototype inline.\n" +
+    "**Output:** Write to .renn/design/implementation-guide.md\n" +
+    "</guide_context>",
+  subagent_type="general-purpose",
+  model="{designer_model}",
+  description="Generate implementation guide for CSS framework: " + CSS_FRAMEWORK
+)
+```
+
+### 4. Verify Guide Was Created
+
+```bash
+if [ ! -f ".renn/design/implementation-guide.md" ]; then
+  echo "WARNING: Implementation guide was not created. Continuing without guide."
+fi
+```
+
+Display: `Implementation guide generated at .renn/design/implementation-guide.md`
+</step>
+
+<step name="commit_implementation_guide">
+**Trigger:** `generate_implementation_guide` step completed and `.renn/design/implementation-guide.md` exists on disk.
+
+```bash
+if [ "$COMMIT_PLANNING_DOCS" = "true" ] && [ -f ".renn/design/implementation-guide.md" ]; then
+  git add .renn/design/implementation-guide.md
+  git commit -m "docs(${COMMIT_PREFIX}): generate implementation guide
+
+Implementation guide for ${COMMIT_MSG_SCOPE}
+- CSS framework translation mappings
+- Token system bridging: prototype -> project"
+fi
+```
+
+This commit runs for ALL invocation modes (design-system, design-screens), fixing the bug where the implementation guide was never committed on single-design-stage projects.
+</step>
+
+<step name="present_final_status">
+Route to the command's `<offer_next>` section.
+
+Display the design-specific completion banner with actual artifact paths:
+
+**If `HAS_DESIGN=true` AND `PROJECT_LEVEL=true`:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RENN ► PROJECT DESIGN COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Design artifacts:
+  Stylekit:     .renn/design/stylekit.yaml
+  CSS:          .renn/design/stylekit.css
+  Preview:      .renn/design/stylekit-preview.html
+  Components:   .renn/design/components/
+  Guide:        .renn/design/implementation-guide.md
+
+Design system ready. Run /renn.design-screens {N} for each UI stage, then /renn.plan-stage {N}.
+```
+
+**If `HAS_DESIGN=true` AND `PROJECT_LEVEL=false`:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RENN ► DESIGN COMPLETE FOR STAGE {X}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Design artifacts:
+  Stylekit:     .renn/design/stylekit.yaml
+  CSS:          .renn/design/stylekit.css
+  Preview:      .renn/design/stylekit-preview.html
+  Components:   .renn/design/components/
+  Screens:      .renn/design/screens/
+  Guide:        .renn/design/implementation-guide.md
+
+Ready for /renn.plan-stage {X} to create executable runs.
+```
+
+**If `HAS_DESIGN=false` AND `PROJECT_LEVEL=true`:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RENN ► PROJECT DESIGN SKIPPED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Design was skipped for this project.
+
+You can still run /renn.plan-stage {N} for each stage -- they will proceed without design artifacts.
+```
+
+**If `HAS_DESIGN=false` AND `PROJECT_LEVEL=false`:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RENN ► DESIGN SKIPPED FOR STAGE {X}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Design was skipped for this stage.
+
+You can still run /renn.plan-stage {X} -- it will proceed without design artifacts.
+```
+</step>
+
+</process>