v3.29.0: Working Principles + plansDirectory

What Changed

Working Principles added to every project CLAUDE.md

Setup now appends a Working Principles section to your CLAUDE.md with three rules:

• Autonomous bug fixing - Just fix it. Read logs, trace the error, resolve it. Zero hand-holding.
• Staff engineer bar - Before marking anything done, ask: Would a staff engineer approve this? Run tests, check logs, prove correctness.
• Re-evaluate on failure - If an approach is not working after 2 attempts, stop and re-evaluate rather than pushing through.

plansDirectory configured automatically

.claude/settings.json now gets plansDirectory: "./docs/plans" so Claude plan mode saves plans to a git-tracked location instead of a temp directory. Existing custom values are preserved.

Propagation to existing projects

Both changes propagate via setup_refresh() on version change - existing projects pick them up on their next ralph run after updating, not just fresh installs.

v3.28.0: Rename signs to lessons

What Changed

Terminology rename: signs to lessons across the entire codebase. Learned lessons is immediately intuitive without needing context from the original Ralph blog post.

Naming changes

• sign to lesson, signs to lessons, unsign to forget
• signs.json to lessons.json, suggested-signs.txt to suggested-lessons.txt
• /sign skill to /lesson skill
• ralph sign/signs/unsign to ralph lesson/lessons/forget
• All functions, variables, constants, and template IDs renamed

Migration for existing projects

Automatic, no action needed. On first run after update:

• .ralph/signs.json is migrated to .ralph/lessons.json (JSON key rewritten)
• .ralph/suggested-signs.txt is renamed to .ralph/suggested-lessons.txt
• Migration triggers from all CLI commands, not just run or setup

Other changes

• Removed cost display from activity feed (inaccurate on max plans, shows duration only)
• Extracted _migrate_signs_to_lessons() helper to deduplicate migration logic in setup.sh

Stats

• 45 files changed, 672 insertions, 637 deletions
• 212 tests passing across 15 test files

v3.27.1 — fix: bump version to 3.27.1 for bash 3.2 + stderr escape sequence fixes

Changes

• fix: bump version to 3.27.1 for bash 3.2 + stderr escape sequence fixes
• fix: write terminal escape sequences to stderr, not stdout
• fix: bash 3.2 unbound variable when run_loop called with no args

Full Changelog: v3.27.0...v3.27.1

v3.27.0

Whats New

Auto-run setup after package update

• No more manual npx agentic-loop setup after updates — skills, hooks, and signs auto-sync when the package version changes
• Version-change detection on ralph run triggers a lightweight setup_refresh

Fix /tab-rename

• Detects terminal via TERM_PROGRAM (iTerm2 vs Terminal.app) instead of blind osascript trial-and-error
• Uses ANSI escape sequences for reliable cross-terminal support
• Tip for oh-my-zsh users whose shell resets the title

AskUserQuestion in /prd

• Source selection, hardening, PRD conflict, and review steps now use clickable options
• Existing PRD defaults to append (no confirmation prompt)
• PRD review is multi-select: approve + edit + re-validate in any combination

Bug fix

• Fix counter arithmetic exit code under set -e in signs merge

v3.26.1

Fixes

Terminal tint now sets light text on dark backgrounds

Users with light terminal themes (dark text on light background) could not read output after Ralph applied a dark tint. Ralph now detects dark backgrounds and switches text to light (#e0e0e0). Original text and background colors are both restored on exit.

Bash 3.2 empty array crash

npx agentic-loop run (with no arguments) crashed on macOS default bash 3.2 with _original_args[@]: unbound variable. Fixed with the standard bash 3.2 empty-array workaround.

v3.26.0

What's New

/tab-rename — Name your terminal tabs

Rename the current terminal tab so you can tell your Claude Code sessions apart. No more five tabs all showing ...skip-permissions.

Works in macOS Terminal.app and iTerm2 via osascript.

README rewrite — plan-first pipeline

The README now shows the actual workflow as a clear pipeline: plan mode → /prd → /prd-check → ralph run

The ASCII diagram and Quick Start section reflect this plan-first approach.

Docs updates

• Added /tab-rename to SKILLS.md, CHEATSHEET.md, and CUSTOMIZATION.md
• Added missing /color documentation to SKILLS.md

v3.25.0

What's New

• Auto-update check - Ralph now checks npm for newer versions once per day when you run npx agentic-loop run. If an update is available, it offers to install it and restart automatically. Skips silently if offline. Detects your install method (local, global, or npx) and uses the right update command.

v3.24.0

What's New

• /color slash command - Pick Ralph's terminal background tint (dark teal, dark purple, dark red, custom hex, or off)
• Configurable terminal tint - terminalTint in .ralph/config.json lets the loop read your preferred color instead of hardcoding
• UAT story-state-protection test - New test coverage for story state protection
• Docs refresh - Updated cheatsheet, customization guide, architecture, workflow, skills, troubleshooting, and getting started docs
• Removed deprecated /idea skill - Use /prd instead
• Improved PRD validation - Updated prd-check skill and validation scripts
• Hooks installer improvements - Refreshed hook installation and setup scripts

v3.23.0 — feat: enforce real behavioral tests and E2E coverage in PRD validation

Changes

• feat: enforce real behavioral tests and E2E coverage in PRD validation
• Update README with enhancements and usage instructions
• Update README with command usage details
• Update README with optional command clarification
• Update CLI command format in README
• fix: pre-commit hooks, writing style defaults, and my-dna template

Full Changelog: v3.22.1...v3.23.0

v3.22.1 — fix: warn when hook copy fails instead of silent continue

Changes

• fix: warn when hook copy fails instead of silent continue

Full Changelog: v3.22.0...v3.22.1