Ralph Tui

Ralph TUI - Autonomous Task Execution

Break down complex work into tasks, then let AI execute them autonomously.

Why this matters: Instead of manually prompting for each step, define the work upfront as a PRD, then let ralph-tui orchestrate execution. It selects tasks, builds prompts with context, executes your AI agent, and advances automatically.

Usage

/ralph-tui                    # Show available commands
/ralph-tui run                # Run autonomous loop on current prd.json
/ralph-tui create             # Create a new PRD with AI assistance
/ralph-tui status             # Check execution status

On Skill Invoke

If no args or "help":

Show the ralph-tui command reference:

Ralph TUI - AI Agent Loop Orchestrator

Commands:
  jfl ralph run --prd ./tasks/file.json    Run autonomous task loop
  jfl ralph create-prd --chat              Create PRD with AI
  jfl ralph setup                          Initialize in project
  jfl ralph status                         Show session status
  jfl ralph resume                         Resume paused session

Quick Start:
  1. Create PRD: jfl ralph create-prd --chat
  2. Run loop:   jfl ralph run --prd ./tasks/my-feature.json

Keyboard (in TUI):
  s = start, p = pause, q = quit
  j/k = navigate, Enter = details

If "run" or "start":

1. Check for prd.json files:

ls ./tasks/*.json 2>/dev/null || ls ./prd.json 2>/dev/null

2. If found, ask which to run:

Found PRD files:
1. tasks/admin-dashboard-prd.json (15 stories)
2. tasks/auth-migration.json (8 stories)

Which PRD to execute? (or 'new' to create one)

3. Launch ralph-tui:

jfl ralph run --prd <selected-file>

If "create" or "new":

1. Ask about the work:

What do you want to build or accomplish?
(Describe the feature, fix, or task - I'll break it into stories)

2. Launch the chat-based PRD creator:

jfl ralph create-prd --chat --output ./tasks/

3. After PRD is created, offer to run it:

PRD created: ./tasks/my-feature.json

Want to start autonomous execution?
  jfl ralph run --prd ./tasks/my-feature.json

If "status":

Check ralph-tui status:

jfl ralph status

Show current session info, completed tasks, remaining work.

PRD Format

Ralph TUI uses JSON PRDs with this structure:

{
  "name": "Feature Name",
  "description": "What we're building",
  "quality_gates": ["bun run typecheck", "bun run lint"],
  "stories": [
    {
      "id": "US-001",
      "title": "Story title",
      "priority": 1,
      "status": "pending",
      "description": "What to implement",
      "acceptance_criteria": ["Criterion 1", "Criterion 2"],
      "files": ["path/to/file.ts"],
      "dependencies": ["US-000"],
      "context": "Additional context for the agent"
    }
  ]
}

Story Fields

Creating Good PRDs

1. Keep Stories Small

Each story should be completable in one agent session (typically <30 min of AI work).

Bad: "Implement user authentication" Good: "Add login form component", "Create auth API route", "Add session middleware"

2. Clear Acceptance Criteria

Make criteria specific and testable.

Bad: "Should work well" Good: "Returns 401 for invalid credentials", "Sets httpOnly cookie on success"

3. Order Dependencies

Put foundational work first. Use dependencies field when order matters.

4. Include Context

Add relevant info the agent needs but won't find in the codebase.

{
  "context": "We're using Drizzle ORM. The users table already has an isAdmin column."
}

Execution Model

1. Task Selection: Ralph picks the highest-priority pending task with no blocked dependencies
2. Prompt Building: Combines task details with your project context (CLAUDE.md, etc.)
3. Agent Execution: Runs your AI agent (Claude Code, OpenCode, etc.)
4. Completion Detection: Watches for <promise>COMPLETE</promise> token
5. Quality Gates: Runs checks (typecheck, lint) before advancing
6. Loop: Moves to next task automatically

Integration with JFL

Ralph TUI is bundled with JFL CLI:

# Install JFL (includes ralph-tui)
npm install -g jfl

# Use ralph via jfl
jfl ralph run --prd ./tasks/feature.json

# Or directly
ralph-tui run --prd ./tasks/feature.json

PRDs are typically stored in ./tasks/ directory within your GTM workspace.

Best Practices

1. Start with /spec: Use /spec skill to refine your PRD through adversarial review before execution
2. Run quality gates: Always include typecheck/lint in quality_gates
3. Review between tasks: Use p to pause and review changes before continuing
4. Keep context files updated: Ralph reads CLAUDE.md for project context

Docs

Full documentation: https://ralph-tui.com/docs

Installed docs: knowledge/RALPH_TUI_DOCS.txt