refactor(loop): consolidated round-2 improvements

.claude/agents/code-quality-reviewer.md

@@ -0,0 +1,132 @@
+---
+name: code-quality-reviewer
+description: "Use this agent when the user wants to improve code quality, review recently written code for issues, refactor existing code, or get suggestions for better patterns and practices. This includes requests to review a file, clean up code, improve readability, reduce complexity, fix code smells, or apply best practices.\\n\\nExamples:\\n\\n- Example 1:\\n  user: \"I just finished implementing the new integration class, can you review it?\"\\n  assistant: \"Let me use the code-quality-reviewer agent to analyze your new integration class for quality improvements.\"\\n  (The assistant launches the code-quality-reviewer agent via the Task tool to review the recently written integration class.)\\n\\n- Example 2:\\n  user: \"This function feels messy, can you help clean it up?\"\\n  assistant: \"I'll use the code-quality-reviewer agent to analyze the function and suggest improvements.\"\\n  (The assistant launches the code-quality-reviewer agent via the Task tool to review and suggest refactoring for the messy function.)\\n\\n- Example 3:\\n  user: \"Can you check my recent changes for any issues?\"\\n  assistant: \"I'll launch the code-quality-reviewer agent to review your recent changes for potential issues and improvements.\"\\n  (The assistant launches the code-quality-reviewer agent via the Task tool to review the recent diff or modified files.)\\n\\n- Example 4 (proactive usage):\\n  Context: The user has just written a substantial block of new code.\\n  user: \"Okay, I think that feature is done.\"\\n  assistant: \"Great! Now let me use the code-quality-reviewer agent to review the code you just wrote and make sure it's solid before we move on.\"\\n  (The assistant proactively launches the code-quality-reviewer agent via the Task tool to review the newly written code.)"
+model: opus
+color: green
+memory: project
+---
+
+You are an elite code quality engineer with deep expertise in software craftsmanship, clean code principles, design patterns, and language-specific best practices. You have decades of experience reviewing production codebases across multiple languages and frameworks, with a particular strength in TypeScript/JavaScript ecosystems. You approach code review with a constructive, educational mindset—your goal is not just to identify issues but to help developers understand *why* something should change and *how* to make it better.
+
+## Core Responsibilities
+
+You review recently written or modified code and provide actionable, prioritized feedback to improve its quality. You focus on code that was recently changed or written, not the entire codebase, unless explicitly asked otherwise.
+
+## Review Methodology
+
+When reviewing code, systematically evaluate these dimensions in order of importance:
+
+### 1. Correctness & Bugs
+- Logic errors, off-by-one errors, race conditions
+- Null/undefined handling and edge cases
+- Error handling completeness (are errors caught, logged, and handled appropriately?)
+- Type safety issues (especially in TypeScript: `any` abuse, missing type guards, unsafe casts)
+
+### 2. Security
+- Input validation and sanitization
+- Secrets or credentials in code
+- Injection vulnerabilities (SQL, command, path traversal)
+- Unsafe deserialization or eval usage
+
+### 3. Architecture & Design
+- Single Responsibility Principle violations
+- Inappropriate coupling between modules
+- Missing abstractions or over-abstraction
+- Consistency with existing codebase patterns
+- Proper separation of concerns
+
+### 4. Readability & Maintainability
+- Naming clarity (variables, functions, classes, files)
+- Function length and complexity (cyclomatic complexity)
+- Code duplication (DRY violations)
+- Comment quality (missing where needed, excessive where code should be self-documenting)
+- Consistent formatting and style
+
+### 5. Performance
+- Unnecessary computations or allocations
+- N+1 query patterns or inefficient data access
+- Memory leaks (event listeners, subscriptions, closures)
+- Algorithmic complexity concerns
+
+### 6. Testing & Testability
+- Is the code structured to be testable?
+- Are there missing test cases for the logic?
+- Are edge cases covered?
+
+## Output Format
+
+Structure your review as follows:
+
+**Summary**: A 1-3 sentence overview of the code's overall quality and the most important finding.
+
+**Critical Issues** (must fix):
+- Each issue with: location, description, why it matters, and a concrete fix
+
+**Improvements** (should fix):
+- Each suggestion with: location, current state, proposed improvement, and rationale
+
+**Minor Suggestions** (nice to have):
+- Style, naming, or minor readability tweaks
+
+**What's Done Well**:
+- Highlight genuinely good patterns to reinforce positive practices
+
+## Review Principles
+
+1. **Be specific**: Always reference exact lines, functions, or patterns. Never give vague feedback like "improve error handling" without saying exactly where and how.
+2. **Provide fixes, not just complaints**: Every issue should include a concrete code suggestion or clear description of the fix.
+3. **Prioritize ruthlessly**: A review with 3 critical findings is more valuable than one with 30 nitpicks. Lead with what matters most.
+4. **Respect existing patterns**: If the codebase has established conventions, suggest improvements that align with them rather than introducing entirely new patterns.
+5. **Be constructive**: Frame feedback as improvements, not criticisms. Use "Consider..." or "This could be improved by..." rather than "This is wrong."
+6. **Context matters**: Consider the purpose of the code. A quick prototype has different quality standards than a production API endpoint.
+
+## Project-Specific Guidelines
+
+When working in projects with specific coding standards (from CLAUDE.md or similar configuration):
+- Always check for and respect project-specific linting rules, formatting standards, and architectural patterns
+- Verify import styles match project conventions (e.g., ESM imports with `.js` extensions in TypeScript projects)
+- Check that the correct package manager is used in any scripts or commands
+- Ensure changes align with the project's stated priorities and patterns
+
+## Self-Verification
+
+Before delivering your review:
+1. Re-read each finding—is it actionable and specific?
+2. Verify your suggested fixes are syntactically correct
+3. Check that you haven't contradicted yourself
+4. Ensure your priority ordering is correct (critical issues first)
+5. Confirm you've looked at the actual changed/new code, not unrelated files
+
+## Edge Cases
+
+- If the code is too short or trivial for meaningful review, acknowledge this and focus on any improvements that would still add value.
+- If you need more context (e.g., related files, the purpose of the code, or the broader architecture), ask for it before proceeding with assumptions.
+- If the code is generally excellent, say so clearly and focus your review on minor polish items.
+
+**Update your agent memory** as you discover code patterns, style conventions, common issues, architectural decisions, and recurring quality concerns in this codebase. This builds up institutional knowledge across conversations. Write concise notes about what you found and where.
+
+Examples of what to record:
+- Recurring code smells or anti-patterns you've seen across reviews
+- Project-specific conventions and style preferences
+- Architectural patterns and module relationships
+- Common error handling approaches used in the codebase
+- Testing patterns and coverage gaps you've identified
+
+# Persistent Agent Memory
+
+You have a persistent Persistent Agent Memory directory at `/Users/ruben/learn/ralph-starter/.claude/agent-memory/code-quality-reviewer/`. Its contents persist across conversations.
+
+As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
+
+Guidelines:
+- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise
+- Create separate topic files (e.g., `debugging.md`, `patterns.md`) for detailed notes and link to them from MEMORY.md
+- Record insights about problem constraints, strategies that worked or failed, and lessons learned
+- Update or remove memories that turn out to be wrong or outdated
+- Organize memory semantically by topic, not chronologically
+- Use the Write and Edit tools to update your memory files
+- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
+
+## MEMORY.md
+
+Your MEMORY.md is currently empty. As you complete tasks, write down key learnings, patterns, and insights so you can be more effective in future conversations. Anything saved in MEMORY.md will be included in your system prompt next time.

README.md

@@ -451,6 +451,7 @@ This creates:
 |---------|-------------|
 | `ralph-starter` | Launch interactive wizard |
 | `ralph-starter run [task]` | Run an autonomous coding loop |
+| `ralph-starter fix [task]` | Fix build errors, lint issues, or design problems |
 | `ralph-starter auto` | Batch-process issues from GitHub/Linear |
 | `ralph-starter integrations <action>` | Manage integrations (list, help, test, fetch) |
 | `ralph-starter plan` | Create implementation plan from specs |
@@ -561,6 +562,31 @@ ralph-starter run --circuit-breaker-failures 2 "build Y"
 | `--output-dir <path>` | Directory to run task in (skips prompt) |
 | `--prd <file>` | Read tasks from markdown |
 
+## Options for `fix`
+
+| Flag | Description |
+|------|-------------|
+| `--scan` | Force full project scan (build + lint + typecheck + tests) |
+| `--agent <name>` | Specify agent to use (default: auto-detect) |
+| `--commit` | Auto-commit the fix |
+| `--max-iterations <n>` | Max fix iterations (default: 3) |
+| `--output-dir <path>` | Project directory (default: cwd) |
+
+```bash
+# Fix build/lint errors automatically
+ralph-starter fix
+
+# Fix a specific design/visual issue
+ralph-starter fix "fix the paddings and make the colors brighter"
+
+# Full scan with auto-commit
+ralph-starter fix --scan --commit
+```
+
+For design-related tasks (CSS, colors, spacing, etc.), the fix command automatically:
+- Detects and applies installed design skills
+- Instructs the agent to visually verify changes via browser screenshots
+
 ## Config Commands
 
 ```bash

docs/docs/cli/fix.md

@@ -0,0 +1,167 @@
+---
+sidebar_position: 2
+title: fix
+description: Fix build errors, lint issues, or design problems
+keywords: [cli, fix, command, build errors, lint, design, visual, css]
+---
+
+# ralph-starter fix
+
+Fix build errors, lint issues, or design problems.
+
+## Synopsis
+
+```bash
+ralph-starter fix [task] [options]
+```
+
+## Description
+
+The `fix` command runs a focused AI loop to fix project issues. It scans for build, lint, typecheck, and test failures, then orchestrates a coding agent to fix them automatically.
+
+When given a custom task describing a visual or design problem (e.g., "fix the paddings and make the colors brighter"), the fix command detects CSS/design keywords and:
+
+- Auto-applies installed design skills (frontend-design, ui-ux-designer, etc.)
+- Instructs the agent to visually verify changes using browser screenshots
+
+For structured visual fix passes, use the `--design` flag — see [Design Mode](#design-mode) below.
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `task` | Optional description of what to fix. If not provided, scans for build/lint errors. |
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan` | Force full project scan (build + lint + typecheck + tests) | false |
+| `--design` | Structured visual fix mode with screenshot verification | false |
+| `--agent <name>` | Specify agent (claude-code, cursor, codex, opencode) | auto-detect |
+| `--commit` | Auto-commit the fix | false |
+| `--max-iterations <n>` | Maximum fix iterations | 3 (scan), 4 (design keywords), 7 (--design) |
+| `--output-dir <path>` | Project directory | cwd |
+
+## Examples
+
+### Fix Build Errors
+
+```bash
+# Auto-detect and fix build/lint errors
+ralph-starter fix
+
+# Force full project scan
+ralph-starter fix --scan
+```
+
+### Fix Design Issues
+
+```bash
+# Structured visual fix pass (recommended for design work)
+ralph-starter fix --design
+
+# Design mode with specific notes
+ralph-starter fix --design "the hero section spacing is off and colors are too muted"
+
+# Ad-hoc CSS/design fix (auto-detected as design task)
+ralph-starter fix "fix the paddings and make the colors brighter"
+
+# Fix responsive layout
+ralph-starter fix "make the layout responsive on mobile"
+```
+
+### With Options
+
+```bash
+# Auto-commit the fix
+ralph-starter fix --scan --commit
+
+# Use a specific agent
+ralph-starter fix "fix lint errors" --agent claude-code
+
+# Allow more iterations for complex fixes
+ralph-starter fix "fix all test failures" --max-iterations 5
+
+# Design fix with more room to iterate
+ralph-starter fix --design --max-iterations 10
+```
+
+## Behavior
+
+1. **Error Detection**:
+   - If `task` provided → runs build check for baseline, then fixes the described issue
+   - If no task and previous failures exist → re-runs failed validations from `.ralph/activity.md`
+   - If `--scan` → runs full validation suite (build + lint + typecheck + tests)
+
+2. **Skill Detection**:
+   - Detects installed Claude Code skills relevant to the task
+   - For CSS/design tasks → auto-applies design skills and adds visual verification instructions
+   - Searches skills.sh for complementary skills if needed
+
+3. **Fix Loop**:
+   - Agent works on fixing issues (default: 3 iterations for scan, 7 for `--design`)
+   - Lint checks run between iterations (fast feedback)
+   - Full build check runs on final iteration
+   - If build fails on final iteration → extends loop by 2 extra iterations
+
+4. **Verification**:
+   - Re-runs original validation commands after the loop
+   - Reports success only if all checks pass (not just agent completion)
+
+## Design Mode
+
+The `--design` flag enables a structured visual fix workflow specifically designed for CSS, layout, and styling issues. It runs the agent through a 5-phase process:
+
+### Phase 1: Visual Audit
+
+The agent's **first action** is to start the dev server and take screenshots at 3 viewports:
+- Desktop (1440px)
+- Tablet (768px)
+- Mobile (375px)
+
+### Phase 2: Issue Identification
+
+The agent analyzes screenshots against the project spec and checks for issues in priority order:
+
+0. **CSS cascade conflicts** — Detects unlayered CSS resets (e.g., `* { margin: 0; padding: 0; }`) that silently override Tailwind v4 utilities. This is the most common cause of "classes are correct but nothing works."
+1. **Page structure** — Content centering, max-width wrappers, empty gaps
+2. **Layout & positioning** — Grid/flex rendering, column balance, overlaps
+3. **Responsive issues** — Viewport breakage, overflow, clipping
+4. **Spacing** — Vertical rhythm, abnormal gaps
+5. **Typography & colors** — Font loading, readability, consistency
+
+### Phase 3: Fix Plan
+
+The agent creates a `DESIGN_FIX_PLAN.md` with specific issues, exact files, and CSS properties to change.
+
+### Phase 4: Execute & Verify
+
+Fixes are applied in priority order (structural first, cosmetic last). The agent re-screenshots after each structural fix to verify improvement.
+
+### Phase 5: Completion
+
+The loop requires the agent to output `DESIGN_VERIFIED` after taking final verification screenshots. The loop will **not** accept generic completion signals like "All tasks completed" — only `DESIGN_VERIFIED` after visual confirmation.
+
+### Why Design Mode Exists
+
+Without `--design`, agents often:
+- Read code and see "correct" Tailwind classes, then declare victory without visual verification
+- Add more CSS classes on top of cascade conflicts instead of fixing the root cause
+- Complete in 1 iteration without actually verifying the visual result
+
+Design mode forces visual-first debugging and prevents premature exit.
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | All issues fixed |
+| 1 | Could not fix all issues automatically |
+
+## See Also
+
+- [ralph-starter run](/docs/cli/run)
+- [ralph-starter skill](/docs/cli/skill)
+- [Validation](/docs/advanced/validation)
+- [Skills System](/docs/guides/skills-system)

docs/docs/cli/skill.md

@@ -125,17 +125,11 @@ and included in the agent's prompt context when relevant.
 
 ## Auto Skill Discovery
 
-Auto skill discovery is opt-in. When enabled, ralph-starter
-queries the skills.sh registry to find and install relevant
-skills automatically.
+Auto skill discovery is enabled by default. ralph-starter
+queries the skills.sh API to find and install relevant
+skills automatically before each run.
 
-Enable it by setting:
-
-```bash
-RALPH_ENABLE_SKILL_AUTO_INSTALL=1
-```
-
-You can also force-disable it with:
+To disable it, set:
 
 ```bash
 RALPH_DISABLE_SKILL_AUTO_INSTALL=1

docs/docs/community/changelog.md

@@ -11,6 +11,24 @@ All notable changes to ralph-starter are documented here. This project follows [
 
 ---
 
+## [0.1.1-beta.17] - 2026-02-14
+
+### Added
+- **`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 now default to Tailwind CSS + shadcn/ui + motion-primitives when no styling is specified (framework-aware: shadcn-vue for Vue, shadcn-svelte for Svelte)
+- **`uiLibrary` field** in TechStack for explicit UI component library selection
+- **Rich spec generation**: Specs and AGENTS.md now include Tailwind v4 setup notes, CSS cascade layer warnings, and shadcn component setup instructions
+
+### Fixed
+- Design loop premature exit — `fix --design` now requires explicit `DESIGN_VERIFIED` token after visual confirmation (prevents 1-iteration false completions)
+- Design loop stall detection — screenshot/viewport analysis no longer falsely triggers idle detection
+- Default design iterations increased from 5 to 7 for more thorough visual fixes
+
+### Changed
+- Completion instruction in agent preamble is now conditional — design mode uses task-specific completion flow instead of generic "All tasks completed"
+
+---
+
 ## [0.1.1-beta.16] - 2026-02-07
 
 ### Added