feat: v0.3.0 — smart UI defaults, fix --design mode, loop engine overhaul

[rubenmarcus]

Summary

• fix --design mode: Structured 5-phase visual fix workflow with screenshot verification, CSS cascade conflict detection, and DESIGN_VERIFIED completion token
• Smart UI defaults: Web projects default to Tailwind CSS v4 + shadcn/ui + motion-primitives (framework-aware: shadcn-vue for Vue, shadcn-svelte for Svelte)
• Rich spec generation: Specs and AGENTS.md include Tailwind v4 setup notes, CSS cascade layer warnings, and shadcn component setup instructions
• Loop engine overhaul: Git-independent change detection, task-aware stall detection, memoized plan parsing, cost ceilings, 20+ reliability/performance fixes
• Version bump to 0.3.0

Key Changes

Smart UI Defaults (Part A)

• Added uiLibrary field to TechStack interface
• Web projects default to shadcn + tailwind + motion-primitives when no styling specified
• Updated REFINEMENT_PROMPT to suggest UI libraries
• Framework-aware: shadcn/ui for React, shadcn-vue for Vue, shadcn-svelte for Svelte

Rich Spec Generation (Part B)

• Specs include Tailwind v4 Setup Notes section with cascade layer warnings
• AGENTS.md includes explicit "Do NOT add manual CSS resets" instructions
• shadcn UI Components section with setup commands

Design Fix Loop (Part C)

• fix --design requires DESIGN_VERIFIED token for completion
• CSS cascade conflict detection as priority 0 check
• Default iterations increased to 7 for design mode
• Screenshot/viewport activity prevents false stall detection

Loop Defense (Part D)

• Design activity (screenshots) credited in stall detection
• Conditional preamble: design mode uses task-specific completion flow

Test plan

• pnpm build — clean (0 errors)
• pnpm test — 171/171 passing
• Manual: run ralph-starter wizard → verify UI library defaults in summary
• Manual: run ralph-starter fix --design → verify 5-phase flow

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

Issue Linking Reminder

This PR doesn't appear to have a linked issue. Consider linking to:

• This repo: Closes #123
• ralph-ideas: Closes multivmlabs/ralph-ideas#123

Using Closes, Fixes, or Resolves will auto-close the issue when this PR is merged.

---

If this PR doesn't need an issue, you can ignore this message.

[github-actions]

✔️ Bundle Size Analysis

Metric	Value
Base	1847.13 KB
PR	1847.13 KB
Diff	0 KB (0%)

Bundle breakdown

156K	dist/auth
28K	dist/automation
4.0K	dist/cli.d.ts
4.0K	dist/cli.d.ts.map
16K	dist/cli.js
12K	dist/cli.js.map
460K	dist/commands
28K	dist/config
4.0K	dist/index.d.ts
4.0K	dist/index.d.ts.map
4.0K	dist/index.js
4.0K	dist/index.js.map
536K	dist/integrations
84K	dist/llm
728K	dist/loop
172K	dist/mcp
32K	dist/presets
92K	dist/setup
36K	dist/skills
392K	dist/sources
76K	dist/ui
84K	dist/utils
336K	dist/wizard

[github-actions]

🔗 Docs Preview

Preview URL: https://test-round2-improvements.ralph-starter-docs.pages.dev

This preview was deployed from the latest commit on this PR.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR delivers four major improvements to ralph-starter's autonomous loop engine and wizard experience:

Smart UI Defaults: Web projects now default to Tailwind CSS v4 + framework-appropriate shadcn variant (shadcn/ui for React, shadcn-vue for Vue, shadcn-svelte for Svelte) + motion-primitives when no styling is specified. The wizard LLM prompt and spec generator produce rich technical documentation including Tailwind v4 setup instructions, CSS cascade layer warnings, and shadcn component installation commands.

Design Fix Mode: New fix --design command implements a structured 5-phase visual fix workflow requiring screenshot verification and explicit DESIGN_VERIFIED completion token. Priority 0 check detects CSS cascade conflicts (unlayered CSS overriding Tailwind utilities). Design mode increases default iterations to 7 and credits screenshot/viewport activity in stall detection.

Loop Engine Overhaul: 20+ reliability and performance improvements including git-independent change detection via filesystem snapshots, task-aware stall detection with design activity credit, memoized plan parsing with mtime cache, cost ceiling enforcement, dynamic iteration budget adjustment when plans expand, and refactored completion detection combining status and reason in a single pass.

Package Manager Awareness: New utility detects package manager from lock files and package.json, ensuring validation commands use the correct PM (pnpm/npm/yarn/bun) rather than hardcoded npm.

Confidence Score: 4/5

• Safe to merge with minor verification - all tests pass, build clean, changes are well-structured
• Score reflects comprehensive testing (171/171 tests passing, clean build) and well-architected changes across 45 files. The PR introduces significant new functionality (design fix mode, smart UI defaults) and major loop engine refactors, but follows established patterns and includes proper error handling. Minor points deducted for: (1) large surface area of changes (900+ lines in executor.ts alone increases review complexity), (2) new fix command should be manually tested with --design flag as noted in test plan, (3) memoization cache in task-counter could theoretically have race conditions in concurrent scenarios.
• Pay close attention to src/commands/fix.ts (new command, should be manually tested), src/loop/executor.ts (major refactor with many edge cases), and src/loop/task-counter.ts (mtime-based memoization cache).

Important Files Changed

Filename	Overview
src/commands/fix.ts	New fix command with design mode support - comprehensive visual fix workflow with 5 phases, CSS cascade detection, and DESIGN_VERIFIED completion token
src/wizard/llm.ts	Smart UI defaults implementation - defaults to Tailwind + framework-aware shadcn variant (shadcn/shadcn-vue/shadcn-svelte) for web projects
src/wizard/spec-generator.ts	Rich spec generation with Tailwind v4 setup notes, CSS cascade warnings, shadcn component instructions, and package manager detection
src/loop/executor.ts	Major loop engine overhaul - git-independent change detection, stall detection with design activity credit, cost ceilings, memoized plan parsing, completion refactor
src/loop/validation.ts	Added detectBuildCommands, detectLintCommands, package manager aware validation commands, and removed early-exit-on-failure behavior
src/loop/task-counter.ts	Memoized plan parsing with mtime cache, estimateTasksFromContent for spec-based estimation, increased buffers and max iterations to 25
src/utils/package-manager.ts	New utility for package manager detection (lock files + package.json) and run command formatting

Flowchart

flowchart TD
    Start([ralph-starter fix --design]) --> ParseActivity{Parse .ralph/activity.md}
    ParseActivity -->|Failed validations found| ActivityMode[Mode: activity]
    ParseActivity -->|No failures| ScanMode[Mode: scan]
    
    ActivityMode --> RunValidation[Run validation commands]
    ScanMode --> RunValidation
    
    RunValidation --> CheckFailures{Build errors?}
    CheckFailures -->|No errors & no custom task| Done1([Exit: Nothing to fix])
    CheckFailures -->|Has errors| BuildFeedback[Format validation feedback]
    
    BuildFeedback --> DetectAgent[Detect best agent]
    DetectAgent --> BuildPrompt[Build design fix prompt]
    
    BuildPrompt --> Phase1[Phase 1: Visual Audit<br/>Start dev server + screenshots<br/>at 3 viewports]
    Phase1 --> Phase2[Phase 2: Issue Identification<br/>Priority 0: CSS cascade conflicts<br/>Priority 1-5: Structure/layout/spacing]
    Phase2 --> Phase3[Phase 3: Fix Plan<br/>Create DESIGN_FIX_PLAN.md]
    Phase3 --> Phase4[Phase 4: Execute & Verify<br/>Fix structural issues first<br/>Re-screenshot after each fix]
    Phase4 --> Phase5[Phase 5: Cleanup<br/>Stop dev server<br/>Output DESIGN_VERIFIED token]
    
    Phase5 --> LoopEngine[Loop executor with options:<br/>maxIterations: 7<br/>completionPromise: DESIGN_VERIFIED<br/>requireExitSignal: true]
    
    LoopEngine --> StallDetection{Stall detection}
    StallDetection -->|Screenshot activity| Credit[Credit as forward progress]
    StallDetection -->|No changes| Stall[Circuit breaker]
    
    Credit --> CheckCompletion{DESIGN_VERIFIED<br/>token found?}
    Stall --> CheckCompletion
    
    CheckCompletion -->|Yes| VerifyFix[Re-run validation commands]
    CheckCompletion -->|Max iterations| VerifyFix
    
    VerifyFix --> AllPass{All checks<br/>passing?}
    AllPass -->|Yes| Done2([Exit: Success])
    AllPass -->|No| Done3([Exit: Partial fix])

Loading

_{Last reviewed commit: 6ebd762}