feat: prompt engine v2 - templates, preview panel, and UX improvements#128
Merged
feat: prompt engine v2 - templates, preview panel, and UX improvements#128
Conversation
added 24 commits
January 17, 2026 08:55
- Add getTemplate() method to TrackerPlugin interface - Implement tracker-owned templates in json, beads, and beads-bv plugins - Update engine.ts to use tracker.getTemplate() as template source - Remove orphaned .hbs template files (were never actually used) - Keep builtin.ts as fallback for backward compatibility Templates now follow context-first structure: PRD → Codebase Patterns → Task Details → Workflow Part of the prompt template improvements initiative.
Resolved conflicts by keeping local template improvements. TODO: Need to manually incorporate sandbox config changes from main.
Added sandbox configuration fields that were in main but lost during merge: - sandboxConfig/sandboxMode fields in IterationLogMetadata - Sandbox handling in buildMetadata() and saveIterationLog() - Proper detection of new options object format
- Add 'prompt' view mode to RightPanel (cycles with 'o', direct access with Shift+O) - Add PromptPreviewView component with markdown highlighting - Add dynamic content warning banner for preview mode - Add generatePromptPreview() method to ExecutionEngine - Update template system to accept ExtendedTemplateContext with PRD data - Add getPrdContext() to TrackerPlugin interface for PRD content loading - Update keyboard shortcuts in theme.ts Users can now preview the full prompt that will be sent to the agent before execution, including PRD content (when available from tracker).
Begin migration to external template files (Option A architecture): - Create beads/ folder with index.ts and template.hbs - Create beads-bv/template.hbs Templates will be installed to ~/.config/ralph-tui/templates/ and users can override in ./.ralph-tui/templates/ WIP: Still need to complete beads-bv, json, and update imports.
…l templates - Create json/ folder with index.ts and template.hbs - Add beads-bv/index.ts with template file reading - External .hbs templates enable user customization - Each tracker now co-locates code and template
- Resolution order: custom → project → global → legacy → tracker → builtin
- Project templates in .ralph-tui/templates/{tracker}.hbs
- Global templates in ~/.config/ralph-tui/templates/{tracker}.hbs
- Add installGlobalTemplates() and installBuiltinTemplates() functions
- Maintain backward compatibility with legacy prompt.md files
- Update builtin/index.ts to import from folder paths - Update convert.ts json import - Update run.tsx beads import - Update test imports for json and beads trackers
Deleted: - builtin/beads.ts → now at builtin/beads/index.ts - builtin/beads-bv.ts → now at builtin/beads-bv/index.ts - builtin/json.ts → now at builtin/json/index.ts
- Add build:templates script to copy .hbs files to dist
- Update beads.test.ts import to use new folder path
- Templates are now in dist/plugins/trackers/builtin/{tracker}/
70 tests covering: - Pure function tests (path helpers, template type mapping) - Template variables and context building - Resolution hierarchy (custom → project → global → tracker → builtin) - Template installation (installGlobalTemplates, installBuiltinTemplates) - Template rendering with Handlebars - Integration tests for template update workflows
Updated overview.mdx: - Document 6-level template resolution hierarchy - Add project templates (.ralph-tui/templates/) - Add global templates (~/.config/ralph-tui/templates/) - Document legacy compatibility Updated customization.mdx: - Explain new folder-based template locations - Document project vs global templates - Update examples for new structure Updated handlebars.mdx: - Add PRD context variables (prdName, prdContent, etc.) - Add codebasePatterns variable - Add selectionReason variable (beads-bv) - Add beadsDbPath variable
- Implement `ralph-tui template init --global` flag that installs all built-in templates to ~/.config/ralph-tui/templates/ - Update CLI help text with correct 6-level template resolution order - Add all template variables to CLI help (PRD, progress, patterns) - Document prompt preview panel (O key) in quick-start guide - Update keyboard shortcuts table with new TUI features - Export installBuiltinTemplates and related functions from templates module
- Update overview.mdx with actual JSON and Beads templates showing: - PRD context with collapsible full document - Codebase patterns section - Progress tracking workflow - Stop conditions for avoiding redundant work - Update customization.mdx "Verbose Template" to include PRD vars - Update handlebars.mdx "Maximum Context" example with: - PRD context (prdName, prdContent, prdCompletedCount, prdTotalCount) - codebasePatterns and selectionReason variables
Update customization.mdx examples to include all built-in template features: - "Verbose Template with Full Context" now includes: - Stop condition section - Learning documentation workflow (progress.md) - beadsDbPath for beads tracker - selectionReason for beads-bv tracker - "Frontend-Focused Template" now includes: - PRD context and progress - Codebase patterns - Recent progress - Stop condition - "API Development Template" now includes: - PRD context and progress - Codebase patterns - Recent progress - Stop condition All examples now mirror the structure of actual built-in templates.
The `codebasePatterns` variable was defined in templates but never populated. This fix: - Export `getCodebasePatternsForPrompt` from logs module - Call it in `buildPrompt()` to include patterns in actual prompts - Call it in `generatePromptPreview()` so TUI preview shows patterns Now the "Codebase Patterns (Study These First)" section will appear in prompts when users have documented patterns in progress.md.
Previously the prompt preview only updated when pressing 'O' or cycling to prompt mode. Now it automatically regenerates when: - The selected task changes (arrow keys) - User is already in prompt view mode This keeps the prompt preview in sync with the currently selected task.
Update workflow step to explicitly tell agents to study progress.md for implementation context, rather than just reviewing injected patterns. This gives agents clearer guidance to: - Understand overall project status - Review implementation progress from previous iterations - Learn codebase patterns and gotchas from documented learnings
Apply same simplifications as json template: - Simplified PRD intro (direct content instead of details wrapper) - Removed codebasePatterns section (agents read progress.md directly) - Cleaner header comments
Fixed stale prompt preview issue with two changes: 1. Refactored useEffect to compute taskId inside the effect using displayedTasks and selectedIndex directly (instead of pre-computed selectedTaskId). This ensures fresh data on each effect run. 2. Added cancellation logic to prevent race conditions when user quickly changes between tasks - stale async results are discarded. Also simplified beads and beads-bv templates to match json template.
Added explicit prompt regeneration in j/k keyboard handlers when in prompt view mode. This ensures the prompt preview updates immediately when navigating between tasks. Also: - Fixed MDX template variable escaping in docs (taskId error) - Updated template examples to match simplified format - Updated workflow step to study progress.md directly
The useEffect already handles prompt regeneration correctly when selectedIndex changes. The manual calls were unnecessary.
MDX was interpreting \{\{\}\} as JSX expressions, causing 'taskId is
not defined' errors. Escaped all curly braces with backslashes per
MDX troubleshooting guide.
Simplify template resolution from 6 levels to 5 by removing legacy support:
- Remove `template init-prompts` command
- Remove legacy path resolution (~/.config/ralph-tui/prompt*.md)
- Delete src/templates/prompts.ts (PROMPT_JSON, PROMPT_BEADS)
- Remove deprecated functions: getDefaultPromptFilename, getUserPromptPath,
getBundledPrompt, initializeUserPrompts
- Update docs to reflect simplified resolution order
New resolution hierarchy:
1. Custom path (--prompt or prompt_template config)
2. Project templates (.ralph-tui/templates/{tracker}.hbs)
3. Global templates (~/.config/ralph-tui/templates/{tracker}.hbs)
4. Tracker plugin bundled template
5. Built-in fallback
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
WalkthroughAdds per-tracker Handlebars templates, template install/resolve and preview plumbing, engine API to generate prompt previews, extended logging with iteration summaries and codebase-pattern extraction, tracker index reorganisation, and TUI support to view prompt previews with new keyboard shortcuts. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant TUI as RunApp / TUI
participant Engine as ExecutionEngine
participant Logs as Logs Module
participant Tracker as TrackerPlugin
participant Template as TemplateEngine
User->>TUI: open prompt preview (O or cycle)
TUI->>Engine: generatePromptPreview(taskId)
Engine->>Logs: getCodebasePatternsForPrompt(cwd)
Logs-->>Engine: codebasePatterns
Engine->>Tracker: getTemplate()
Tracker-->>Engine: trackerTemplate
Engine->>Tracker: getPrdContext?()
Tracker-->>Engine: prdContext
Engine->>Template: renderPrompt(task, config, extendedContext, trackerTemplate)
Template->>Template: loadTemplate(project/global/tracker/builtin)
Template-->>Engine: { renderedPrompt, templateSource }
Engine-->>TUI: { success, preview, templateSource }
TUI->>User: display PromptPreviewView
Estimated code review effort🎯 4 (Complex) | ⏱️ ~75 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
src/logs/progress.ts (1)
184-198: Ensure new progress files include the Codebase Patterns header.
appendProgressstill seedsprogress.mdwith the old header, so fresh files miss the Codebase Patterns section and extraction will return empty. Please usegetDefaultProgressHeader()here as well.🛠️ Proposed fix
- existing = `# Ralph Progress Log - -This file tracks progress across iterations. It's automatically updated -after each iteration and included in agent prompts for context. - ---- - -`; + existing = getDefaultProgressHeader();website/content/docs/templates/customization.mdx (1)
19-23: Quick‑start output path likely out of date.This says
template initcreates.ralph-tui-prompt.hbs, but the rest of the doc (and new hierarchy) centres on.ralph-tui/templates/{tracker}.hbs. Please align this with the current CLI behaviour.
🤖 Fix all issues with AI agents
In `@src/engine/index.ts`:
- Around line 67-92: In buildPrompt the code calls tracker?.getTemplate which
accesses the property but does not safely call it, causing TypeError when
getTemplate is undefined; change the call to use the optional call syntax or
guard the property before invoking (e.g., obtain trackerTemplate via
tracker.getTemplate?.() or check typeof tracker.getTemplate === 'function'
before calling) so trackerTemplate is either the returned template or undefined,
then pass that safe value into renderPrompt; update the symbol references in
buildPrompt (tracker?.getTemplate → tracker.getTemplate?.(), trackerTemplate,
renderPrompt) accordingly.
In `@src/plugins/trackers/builtin/beads-bv/template.hbs`:
- Around line 6-8: Update the comment block in template.hbs that lists
customizable template paths to use the v2 locations: replace legacy "Project:
.ralph-tui-prompt.hbs" and "User: ~/.config/ralph-tui/prompt-beads-bv.hbs" with
the new v2 equivalents (project and user-level v2 paths) so users copying the
template are pointed to the correct directories; edit the comment at the top of
src/plugins/trackers/builtin/beads-bv/template.hbs to reflect these new v2
paths.
In `@src/plugins/trackers/builtin/beads/template.hbs`:
- Around line 5-7: Update the header comment in
src/plugins/trackers/builtin/beads/template.hbs to reflect the new folder-based
template hierarchy: replace the legacy "Project: .ralph-tui-prompt.hbs" and
"User: ~/.config/ralph-tui/prompt-beads.hbs" paths with the new project-local
and global template locations used by the migration (use the repository's new
project templates folder and the global templates directory), ensuring the
comment accurately names the new filenames/paths so users are not misled.
In `@src/tui/components/RunApp.tsx`:
- Around line 760-780: The generatePromptPreview useCallback is being invoked
both by the effect (which supports cancellation) and directly from the keyboard
handler (the 'o' / 'Shift+O' key handler), causing concurrent calls and racey
updates; remove the direct calls from the keyboard handler(s) and any other
places listed (around the blocks at 1028-1047 and 1096-1098) so the effect alone
drives prompt preview generation, leaving generatePromptPreview only used by the
effect and keeping its state updates (setPromptPreview, setTemplateSource)
as-is.
🧹 Nitpick comments (5)
src/plugins/trackers/builtin/beads/index.ts (1)
667-693: Cache the fallback template to avoid repeated read failures.If the file is missing/unreadable, every call will reattempt and log. Caching the fallback keeps behaviour stable and avoids noisy logs.
♻️ Proposed change
- } catch (err) { - console.error(`Failed to read template from ${templatePath}:`, err); - // Return a minimal fallback template - return `## Task: {{taskTitle}} + } catch (err) { + console.error(`Failed to read template from ${templatePath}:`, err); + // Return a minimal fallback template + templateCache = `## Task: {{taskTitle}} {{`#if` taskDescription}} {{taskDescription}} {{/if}} When finished, signal completion with: <promise>COMPLETE</promise> `; + return templateCache; }src/plugins/trackers/builtin/beads-bv/index.ts (1)
703-729: Cache the fallback template to avoid repeated read attempts.Without caching, failures will re-log on every call. Persist the fallback in the cache to keep it quiet and deterministic.
♻️ Proposed change
- } catch (err) { - console.error(`Failed to read template from ${templatePath}:`, err); - // Return a minimal fallback template - return `## Task: {{taskTitle}} + } catch (err) { + console.error(`Failed to read template from ${templatePath}:`, err); + // Return a minimal fallback template + templateCache = `## Task: {{taskTitle}} {{`#if` taskDescription}} {{taskDescription}} {{/if}} When finished, signal completion with: <promise>COMPLETE</promise> `; + return templateCache; }src/templates/builtin.ts (1)
96-117: Consider extracting the common workflow section.The "Workflow", "Before Completing", and "Stop Condition" sections are nearly identical across all three templates (BEADS_TEMPLATE, BEADS_BV_TEMPLATE, JSON_TEMPLATE). While the current approach is clear and readable, you might consider using Handlebars partials in the future to avoid maintenance burden if these instructions need updating.
src/engine/index.ts (1)
800-801: Verify tracker parameter handling.The call to
buildPromptpassesthis.tracker ?? undefined, but the tracker parameter is already optional. The?? undefinedis redundant sincenullwould be handled the same way, though it doesn't cause issues.♻️ Optional simplification
- const prompt = await buildPrompt(task, this.config, this.tracker ?? undefined); + const prompt = await buildPrompt(task, this.config, this.tracker || undefined);Or simply:
- const prompt = await buildPrompt(task, this.config, this.tracker ?? undefined); + const prompt = await buildPrompt(task, this.config, this.tracker ?? undefined);Actually, this is fine as-is since it explicitly converts
nulltoundefinedfor type consistency with the optional parameter.tests/templates/engine.test.ts (1)
600-639: Test helper uses synchronousrequire.The
installGlobalTemplatesInDirhelper function uses synchronousrequire('node:fs')andrequire('node:path')instead of the already-imported modules. While this works, it's inconsistent with the ESM style used in the rest of the file.♻️ Suggested improvement
function installGlobalTemplatesInDir( templatesDir: string, templates: Record<string, string>, force: boolean ): { success: boolean; results: Array<{ file: string; created: boolean; skipped: boolean; error?: string }> } { - const fs = require('node:fs'); - const path = require('node:path'); + // Use already-imported modules from top of file + const fs = require('node:fs'); // Or import { existsSync, mkdirSync, writeFileSync } from 'node:fs'Since this is a test file and the pattern works, this is a minor stylistic concern.
Fixed CI test failures caused by Bun's mock.module() polluting module resolution across test files (see: oven-sh/bun#12823). Changes: - Remove template mock from execution-engine.test.ts (real templates work) - Remove logs mock from integration.test.ts, use real temp directories - Add complete session module exports to status.test.ts mock - Add sandbox formatting/parsing to persistence.ts for round-trip tests - Add __test__ export for internal persistence functions - Increase test timeout from 5000ms to 15000ms for CI stability All 1115 tests pass with 0 failures.
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #128 +/- ##
==========================================
+ Coverage 43.29% 45.66% +2.37%
==========================================
Files 59 58 -1
Lines 12728 13000 +272
==========================================
+ Hits 5510 5936 +426
+ Misses 7218 7064 -154
🚀 New features to boost your workflow:
|
- Fix optional chaining for tracker.getTemplate (use ?.() syntax)
- Update template headers with v2 paths:
- Project: .ralph-tui/templates/{tracker}.hbs
- Global: ~/.config/ralph-tui/templates/{tracker}.hbs
- Remove direct generatePromptPreview calls from keyboard handler
(effect handles generation when detailsViewMode changes)
- Remove unused generatePromptPreview callback (dead code)
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@src/tui/components/RunApp.tsx`:
- Around line 456-489: The effect currently derives taskId from
displayedTasks[selectedIndex], which is incorrect in iterations mode and leaves
the preview stale when no task is selected; change the effect to compute an
effectiveTaskId based on detailsViewMode (use the iteration selection state when
detailsViewMode === 'iterations', otherwise use
displayedTasks[selectedIndex]?.id), immediately clear the preview/template when
effectiveTaskId is undefined, and then run the same async
engine.generatePromptPreview(effectivetaskId) flow (keeping the cancelled flag
and state updates via setPromptPreview and setTemplateSource) so the preview
always matches the current effective task selection.
added 2 commits
January 17, 2026 16:29
Template Engine Tests: - Add tests for tracker template fallback behavior - Add tests for builtin template fallback - Add tests for custom path error handling - Add tests for renderPrompt error cases - Add tests for installGlobalTemplates function behavior - Use unique tracker types to avoid global template pollution Prompt Preview Effect (PR feedback): - Compute effectiveTaskId based on viewMode (iterations vs tasks) - Clear preview when no task is selected - Works correctly in both tasks view and iterations view
- Add tests for acceptance criteria extraction from description (covers lines 218, 226 - ## Acceptance Criteria section and checklist patterns) - Coverage improved from 90.97% to 91.28%
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@tests/templates/engine.test.ts`:
- Around line 523-532: The tests call installBuiltinTemplates and
installGlobalTemplates which write to the real user config
(~/.config/ralph-tui/templates); update the Installation and Error Handling
suites to sandbox the user config by creating a temporary directory (via
createTestDir) and either set HOME/ XDG_CONFIG_HOME to that temp dir or mock
getUserConfigDir to return it before calling
installBuiltinTemplates/installGlobalTemplates, then restore the original
env/getUserConfigDir in afterEach (cleanupTestDir); apply the same sandboxing
pattern to the other affected blocks referenced (around the lines you mentioned)
to avoid polluting developer/CI profiles.
- Around line 1024-1043: The tests in engine.test.ts use platform-specific paths
and invalid-byte sequences which break on non-POSIX systems; update the two
failing tests that call copyBuiltinTemplate to instead create a temporary
directory via the OS temp facility, then (a) for the "invalid destination path"
test, construct an invalid path using path.join(tempDir, 'template.hbs') but
simulate invalid input by passing a clearly invalid filename guarded by
process.platform === 'win32' if needed or by validating copyBuiltinTemplate
rejects filenames with null bytes without actually writing them, and (b) for the
"restricted permissions" test, create a temp directory, set its permissions to
read-only (fs.chmod) and attempt copyBuiltinTemplate into that directory or skip
the test on platforms that don't support chmod; reference the
copyBuiltinTemplate calls to locate and update the tests and add platform guards
so the tests are deterministic across OSes.
This was referenced Jan 19, 2026
This was referenced Jan 27, 2026
This was referenced Feb 3, 2026
sakaman
pushed a commit
to sakaman/ralph-tui
that referenced
this pull request
Feb 15, 2026
feat: prompt engine v2 - templates, preview panel, and UX improvements
This was referenced Mar 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Major overhaul of the template system plus several UX improvements accumulated over multiple development sessions.
Key Features
🎨 Prompt Preview Panel
pto view,ocycles through details → output → prompt📁 Template System v2
template.hbsfile.ralph-tui/templates/{tracker}.hbsfor per-project customization~/.config/ralph-tui/templates/viatemplate init --globalprompt.md/prompt-beads.md- cleaner.hbsonly📋 Clipboard Copy Support
🔍 Historic Iteration Context
🐛 Bug Fixes
Files Changed (51 files)
New Files
src/utils/clipboard.tssrc/templates/engine.test.tssrc/templates/types.tssrc/plugins/trackers/builtin/*/template.hbstests/templates/engine.test.tstests/utils/clipboard.test.tstests/logs/persistence.test.tsModified Files
src/tui/components/RunApp.tsx- Prompt preview integrationsrc/tui/components/RightPanel.tsx- New prompt view modesrc/templates/engine.ts- Hierarchical template resolutionwebsite/content/docs/templates/*.mdx- Updated documentationDeleted Files
src/templates/prompts.ts- Legacy prompt contentsrc/templates/defaults/*.hbs- Replaced by tracker-bundled templatesTest Plan
bun run typecheck- No type errorsbun run build- Builds successfullybun test- All tests passBreaking Changes
template init-promptscommand removed (usetemplate init --globalinstead)~/.config/ralph-tui/prompt.mdfiles no longer usedStats
Summary by CodeRabbit
New Features
Documentation
Chores
✏️ Tip: You can customize this high-level summary in your review settings.