Commit 4921867
feat: v0.3.0 — smart UI defaults, fix --design mode, loop engine overhaul (#189)
* fix(loop): improve validation for greenfield builds
- Reset circuit breaker when tasks advance (prevents false positives
during multi-task greenfield builds where early tasks can't pass tests)
- Add package manager detection: auto-detect pnpm/yarn/bun from lockfiles
and packageManager field instead of hardcoding npm
- Add validation warm-up: skip validation until enough tasks are done for
greenfield builds (auto-detected, configurable via --validation-warmup)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(loop): add stall detection and improve early termination
- Track file changes across all iterations (not just iteration 1)
- Stop loop after 2 consecutive idle iterations (no file changes)
- Check IMPLEMENTATION_PLAN.md for pending tasks in all modes, not
just when task string mentions the plan file
- Lower default max-iterations from 10 to 7 when no plan file exists
Fixes loops running all iterations for simple tasks where the agent
finishes early but the loop doesn't detect completion.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(loop): dynamic iteration calculation from spec content
When no IMPLEMENTATION_PLAN.md exists, estimate task count from the
spec content by analyzing structural elements (headings, bullet
points, numbered lists, checkboxes). This replaces the static
default of 7 with a data-driven estimate.
For the pet shop issue (#86): 4 headings + 12 bullets → ~5 iterations
instead of the old static 10.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(loop): add Ralph Playbook prompt engineering to loop context
- Add loop-aware preamble to every iteration with key Ralph Playbook
language patterns: "study" not "read", "don't assume not implemented",
"no placeholders or stubs", and AGENTS.md self-improvement
- For unstructured specs (no task headers), instruct agent to create
IMPLEMENTATION_PLAN.md as first action instead of generic "implement
all features" prompt
- Add spec file references in iterations 2+ so agent can re-read
requirements from specs/ directory
- Add plan-creation reminder for later iterations without structured tasks
- Use playbook language in structured spec prompt too
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(ux): improve loop UX with ASCII art, smart directory, and calm warnings
- Show Ralph ASCII art in run command via showWelcomeCompact() instead
of plain text header
- Smart project location: detect existing project markers (package.json,
.git, Cargo.toml, etc.) and default to "Current directory" when found
- Fix type:'list' → type:'select' for inquirer v13 compatibility in
project location prompt (same bug fixed across 8 files previously)
- Replace scary [WARNING] silence message with calm chalk.dim status:
"Agent is thinking..." at 30s, "Still working..." at 60s
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(loop): remove iteration delay and fix validation feedback mutation
Speed:
- Remove unnecessary 1-second sleep between loop iterations — saves ~1s
per iteration (25s on a 25-iteration loop)
Bug fix:
- Fix validation feedback mutation that defeated context trimming. The
executor was appending compressed errors to `taskWithSkills` (line 868),
accumulating old validation errors across iterations. Now stores
feedback in a separate variable and passes it through the context
builder's existing `validationFeedback` parameter, which was previously
passed as `undefined` (dead code). The context builder already handles
per-iteration compression (2000 chars for iter 2-3, 500 for 4+).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(loop): fix progress status bug, deduplicate completion detection, improve error hashing
- Fix progress entry always recording 'completed' even for non-done iterations (was ternary with
identical branches). Now records 'partial' for iterations that didn't complete.
- Merge detectCompletion() and getCompletionReason() into single-pass detectCompletionWithReason()
to eliminate duplicate analyzeResponse() calls per iteration.
- Remove unused _validationPassed variable.
- Improve circuit breaker error hashing: only normalize file:line:col locations, timestamps, hex
addresses, and stack traces — preserving semantically meaningful content so different errors
(e.g. "port 8000 in use" vs "file not found") hash differently.
- Add 'partial' status to ProgressEntry type with status badge.
- Update circuit breaker tests for new normalization behavior.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* perf(loop): memoize parsePlanTasks with mtime cache, parallelize agent detection
- Add mtime-based caching to parsePlanTasks() — the same IMPLEMENTATION_PLAN.md file was
being read and regex-parsed 4 times per iteration (init, progress check, completion check,
display). The cache returns the stored result if the file's mtimeMs hasn't changed,
eliminating ~75 redundant file reads across a 25-iteration loop.
- Parallelize agent detection in detectAvailableAgents() — each agent check spawns an
independent subprocess (e.g. `claude --version`). Running them with Promise.all() instead
of sequential for/of cuts startup time from ~2-3s to <1s.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(loop): add cost ceiling, run all validators, output size limit, configurable timeout
Safety:
- Add maxCost option to CostTracker and LoopOptions — the loop checks isOverBudget()
before each iteration and exits with 'cost_ceiling' reason if exceeded. Prevents
unexpected charges on long-running loops.
- Add output size limit (default 50MB) in agent runner — truncates to last 80% of
buffer if exceeded, preventing OOM from verbose agent output.
UX:
- Run all validation commands instead of stopping at first failure — the agent now
sees lint AND test AND build failures in a single pass, enabling multi-fix
iterations instead of fix-one-rerun-fix-another chains.
Configuration:
- Add agentTimeout option to LoopOptions (default: 5 min) — propagated to agent
runner's timeoutMs. Complex tasks can set longer timeouts.
- Add 'cost_ceiling' to LoopResult exit reasons.
- Add 'partial' status to ProgressEntry for non-done iterations.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(circuit-breaker): normalize timestamps before :line:col pattern
Move timestamp regex before the :\d+:\d+ replacement. Previously,
a timestamp like "14:07:39" would match :\d+:\d+ first, mangling it
to "14:N:N" so the timestamp regex could never match. This caused
same errors with different timestamps to hash differently.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(task-counter): add double-stat guard against TOCTOU race in plan cache
The file could change between stat (cache check) and readFileSync.
Now stat before and after reading: only cache if both mtimes match,
preventing stale content from being cached with a new mtime.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: make output truncation repeatable and include stderr in byte accounting
Addresses PR #185 review feedback:
- Remove outputTruncated flag so truncation can fire more than once
- Reset outputBytes after truncation to prevent counter drift
- Include stderr data in byte accounting
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: use full Ralph ASCII art in run command instead of compact version
The compact RALPH_WELCOME_SMALL looked out of place compared to the
full RALPH_FULL art used in the wizard. Use showWelcome() consistently.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(loop): always-on build validation for greenfield projects
Build validation (build + typecheck) now runs after every iteration
regardless of the --validate flag. This catches broken builds early:
- Missing file imports (components that don't exist yet)
- PostCSS/Tailwind misconfiguration
- TypeScript compilation errors
Key changes:
- Add detectBuildCommands() with AGENTS.md > package.json > tsc fallback
- Add runBuildValidation() with 2-min timeout (vs 5-min for full)
- Re-detect build commands per iteration for greenfield projects
- Skip when --validate already covers build/typecheck (no double-run)
- Add preamble rules: "create files before importing" + "verify compilation"
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(loop): filesystem change detection, directory anchoring, greenfield skills
- Add filesystem-based change detection as primary method (git-independent)
- Add getHeadCommitHash() and hasIterationChanges() for git-based secondary detection
- Remove hasChanges gate from build/full validation (unconditional after iter 1)
- Relax stall detection threshold (3 idle + i > 3)
- Add directory anchoring rule to preamble (prevent nested project dirs)
- Strengthen Tailwind v4 rules with exact setup instructions
- Enable skills auto-install by default for greenfield projects (no package.json)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(loop): high-value fixes from code review
context-builder.ts:
- Fix wasTrimmed bug (was always true for iterations > 1)
- Replace unsafe prompt.slice() with semantic trimming at paragraph boundaries
- Section-aware feedback compression (keep first complete section, summarize rest)
task-counter.ts:
- Protect cache from consumer mutation via deep-clone
- Extract MAX_ESTIMATED_ITERATIONS constant (was magic number 25)
task-executor.ts:
- Don't cascade previousBranch on failure (prevents branching from broken state)
- Populate result.cost from loop cost stats (was dead field)
executor.ts:
- Task-aware stall detection (reset idle counter on task progress, not just file changes)
- Post-iteration cost ceiling check (prevents starting expensive iteration over budget)
- Reorder completion detection: cheap checks first, expensive semantic analysis last
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(skills): replace broken CLI search with skills.sh HTTP API
npx skills find is an interactive fzf UI that returns garbage when piped
programmatically. Replace with skills.sh search API (https://skills.sh/api/search)
which returns real repos with install counts. Enable auto-install by default.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(loop): improve resilience and design quality
Loop resilience:
- Increase default iterations 7→10, minimum 3→5, buffer 2→3
- Validation failures no longer count as idle (agent is debugging)
- Relax stall threshold for larger projects (4 idle for 5+ tasks)
Design quality:
- Add anti-AI-aesthetic rules to hard preamble (bans purple gradients,
Inter/Roboto fonts, glass morphism)
- Expand skill auto-apply triggers (page, dashboard, app, shop, store)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(skills): skip install when relevant skills exist, filter irrelevant results
- Check installed skills first: if frontend-design is already installed
and relevant to the task, show "Using installed skills:" and skip API
- Add negative keyword filtering: react-native, mobile, ios, android,
flutter etc. are filtered out for standard web projects
- Use detectClaudeSkills() for comprehensive installed-skill detection
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(skills): install complementary skills, expand queries, max 5
- Don't early-return when skills are installed — always search for
complementary ones (e.g., react-best-practices alongside frontend-design)
- Add React/Vue/Svelte-specific queries (best practices, composition)
- Auto-add SEO query for landing/marketing pages
- Increase max skills from 2 to 5
- Boost scoring for best-practices, composition, guidelines skills
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(loop): dynamic iteration budget + ban dev server in loop
Dynamic iterations:
- maxIterations now recalculates when agent expands the plan
(e.g., spec has 3 tasks → agent creates 8 → budget adjusts to 11)
- Fixes premature "max_iterations" exit on greenfield projects
Ban dev server:
- Preamble now explicitly says "NEVER start a dev server" and to use
npm run build instead. Dev servers block forever, create zombie
processes, and eat up ports (5173, 5174, 5175...) across iterations.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(fix): add fix command with design-aware skill detection and visual verification
- Add `ralph-starter fix` command for autonomous build/design fixing
- Fix skill re-installation bug: normalize skill IDs (spaces vs hyphens) for dedup
- Fix design skills not applied: add CSS/visual keywords to task detection
- Add visual verification instructions for design tasks (web-design-reviewer skill)
- Tiered validation: lint on intermediate iterations, build on final iteration
- Extend loop by 2 iterations when build fails on final iteration
- Fix TOCTOU race condition in task-counter.ts (CodeQL alert #164)
- Ban manual dev server in loop preamble (loop handles validation)
- Export shared WEB_TASK_KEYWORDS to eliminate keyword list divergence
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add fix command to README, CLI docs, and llms.txt
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: regenerate SEO/AEO artifacts from docusaurus build
Rebuild docs and sync auto-generated files (llms.txt, llms-full.txt,
docs.json, ai-index.json, sidebar.json, sitemap.xml, docs-urls.txt)
to include the new fix command documentation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(skills): cap skill installation + filter prompt to top 5 relevant
- Add installation ceiling: skip API search when >=3 relevant skills exist
- Filter formatSkillsForPrompt to only task-relevant skills, capped at 5
- Fix stall detection: lastValidationFeedback is a string (never null),
so `!== null` was always true — use `!!` for correct falsy check
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(context): spec-adherent preamble + include spec summary in iterations 2+
The context builder was dropping all spec content after iteration 1,
causing "spec amnesia" where the agent lost sight of design requirements.
Also, the preamble only had negative design guidance ("NEVER use...") with
no positive instruction to follow the spec faithfully.
- Add buildSpecSummary() to read specs/ directory for later iterations
- Rewrite design section: spec is now "FIRST PRIORITY" source of truth
- Include spec summary in iterations 2-3 and truncated hint in 4+
- Add dev server exception clause for visual verification flows
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(loop): pass spec summary to context builder for iterations 2+
Wire up buildSpecSummary() in the executor so the context builder
can include abbreviated spec content in later iterations, preventing
the agent from losing sight of design requirements.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(skills): add maxSkills parameter to formatSkillsForPrompt
Allow callers to cap the number of skills included in the prompt.
Used by the --design flag to limit to 3-4 focused design skills
instead of the default 5.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(fix): add --design flag for visual-first design fix flow
The fix command was losing all original design context — the agent only
saw the custom task string and build errors, never the spec or plan.
This caused design fixes to be guesswork rather than spec-adherent.
Changes:
- Include specs/ and IMPLEMENTATION_PLAN.md content in fixTask so the
agent knows what "correct" looks like
- Add --design flag: structured screenshot → analyze → plan → fix flow
with 3 viewport breakpoints (desktop/tablet/mobile)
- Bump default iterations: 7 for --design, 5 for design keywords, 3 default
- Clarify dev server override for visual verification
- Register --design option in CLI
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(validation): use detected package manager in detectBuildCommands
detectBuildCommands was hardcoding `npm run build` instead of using
the project's actual package manager (pnpm/yarn/bun). This caused
build validation to fail in projects that enforce a specific pm.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(fix): don't bail early when --design flag is set
The fix command was exiting with "nothing to fix!" when build checks
passed and no custom task was given. But --design targets visual issues
that build checks can't detect, so it should always proceed to the
screenshot/analysis flow.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(fix): cap skills to 4 in --design mode + screenshot-first prompt
Three issues fixed:
- Skills were showing "25 detected" because maxSkills wasn't threaded
through LoopOptions to formatSkillsForPrompt. Now --design caps to 4.
- Startup display now shows "4 active (25 installed)" instead of raw count
- Design prompt now forcefully instructs the agent to start with dev
server + screenshots as the VERY FIRST action, ignoring IMPLEMENTATION_PLAN.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(fix): rewrite --design prompt to catch structural issues first
The design fix prompt was too vague — "layout/spacing problems" led the
agent to suggest padding tweaks instead of catching obvious structural
issues like content not being centered or huge empty gaps.
Rewritten Phase 2 (Issue Identification) to:
- Prioritize page structure (centering, containers, max-width) over cosmetic
- Check for content pinned to edges, broken grid layouts, unbalanced columns
- Require CONCRETE issues visible in screenshots, not generic improvements
Rewritten Phase 3 (Fix Plan) to:
- Require exact file + CSS property for each fix
- Focus on minimal fixes, not redesigning entire components
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(skills): reduce skill bloat in fix command
Pass user's custom task text (not the full generated prompt) to
autoInstallSkillsFromTask. The --design prompt contains dozens of
CSS/design keywords that triggered excessive skill search queries,
causing skills to accumulate globally (25+ after a few runs).
Also lower MAX_SKILLS_TO_INSTALL from 5 to 3 to cap accumulation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(loop): skip IMPLEMENTATION_PLAN.md instructions for fix --design
The preamble said "Study IMPLEMENTATION_PLAN.md and work on ONE task"
which directly conflicted with the --design prompt's "Ignore
IMPLEMENTATION_PLAN.md — this is a visual fix pass." The preamble
appeared first and won, confusing the agent.
Add skipPlanInstructions option that replaces plan-related rules with
"This is a fix/review pass" when active. Set from fix --design.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* perf(fix): reduce default iterations for design tasks
fix --design: 7 → 5 (5-phase structure should complete in 3-4 iters)
isDesignTask: 5 → 4 (visual tasks with keyword detection)
Reduces worst-case wall time from 35min to 25min.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(loop): add iteration log for inter-iteration memory
Each iteration now appends a summary to .ralph/iteration-log.md with
status (validation passed/failed), whether files changed, and agent
summary text. On iterations 2+, the last 3 entries are included in
the prompt as "## Previous Iterations" so the agent knows what was
already tried and can avoid repeating failed approaches.
This is a lightweight alternative to full session continuity (--resume)
which is deferred to 0.3.1.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(loop): better header labels + subtask tree display
- Loop header shows "Design Fix", "Fix", or agent name based on fixMode
instead of always showing "Running Claude Code"
- Subtask tree renders below header when current task has subtasks:
[x] Create hero component
[ ] Add responsive styles
- Add fixMode option to LoopOptions ('design' | 'scan' | 'custom')
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(loop): kill orphaned dev servers after design iterations
After each iteration in design mode, check ports 3000/5173/4321/8080
for orphaned dev server processes and SIGTERM them. This prevents
resource leaks when the agent crashes or times out without cleaning
up the dev server it started for visual verification.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(session): persist validation feedback for resume
Add lastValidationFeedback field to SessionState so that when a
session is paused and later resumed, the agent gets the last
validation errors as context. The resume command now passes this
as initialValidationFeedback to runLoop.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(wizard): add uiLibrary field to TechStack interface
Add uiLibrary as an optional field in TechStack to support UI component
library selection (shadcn/ui, shadcn-vue, shadcn-svelte, MUI, Chakra).
Updated normalizeTechStack, hasTechStack, and the wizard summary display.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(wizard): default to shadcn + tailwind + motion-primitives for web projects
When no UI library/styling is specified, web projects now default to:
- Tailwind CSS for styling
- shadcn/ui (React/Next.js), shadcn-vue (Vue), or shadcn-svelte (Svelte)
Updated REFINEMENT_PROMPT to include uiLibrary field and guidance for
the LLM to suggest this default stack. Template fallback also sets
these defaults when the LLM is unavailable.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(wizard): rich spec + AGENTS.md generation with UI stack details
- Add uiLibrary to spec display (A4)
- Add Tailwind v4 setup instructions to AGENTS.md including cascade
layers warning and explicit "no manual CSS resets" guidance (B1)
- Add shadcn/ui + motion-primitives setup instructions to AGENTS.md (B1)
- Add Setup Notes section to spec with Tailwind v4 + UI library
details to prevent CSS cascade conflicts (B2)
- Add formatTech entries for shadcn, MUI, Chakra, motion-primitives
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(fix): improve --design loop with DESIGN_VERIFIED token + cascade check
- C1: Require DESIGN_VERIFIED completion token for design mode, disable
legacy "All tasks completed" markers via requireExitSignal
- C2: Update Phases 4-5 to instruct agent to emit DESIGN_VERIFIED only
after taking verification screenshots
- C3: Increase default design iterations from 5 to 7 for fix+verify cycles
- C4: Add CSS cascade conflict check as priority 0 in Phase 2 — detects
the "spacing broken + colors working" pattern caused by unlayered CSS
overriding Tailwind v4 @layer utilities
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(loop): design mode stall detection + conditional completion instruction
- D1: Credit screenshot/viewport activity as productive progress in
design mode, preventing stall detector from killing analysis iterations
- D2: Suppress "All tasks completed" instruction for design mode
(skipPlanInstructions=true), replacing with "Follow the completion
instructions in the task below" to avoid conflicting with DESIGN_VERIFIED
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add --design flag, UI defaults, and changelog for beta.17
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: bump version to 0.3.0
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>1 parent 7ade690 commit 4921867
1 file changed
Lines changed: 1 addition & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
| 3 | + | |
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| |||
0 commit comments