create-prd | Ralph TUI

Synopsis

Bash

ralph-tui create-prd [options]

The create-prd command generates a structured PRD through an interactive conversation with an AI agent. It asks about your feature goals, requirements, and quality gates, then produces a PRD Markdown file.

INFO

Use --chat mode (recommended) for AI-powered PRD creation. The AI asks contextual questions and generates higher-quality PRDs than the template wizard.

Aliases

Bash

ralph-tui prime    # Same as create-prd

Options

Option	Description
`--chat`, `--ai`	Use AI-powered chat mode (recommended)
`--agent <name>`	Override agent for chat mode
`--prd-skill <name>`	Use custom PRD skill from `skills_dir`
`--output, -o <dir>`	Output directory for PRD files (default: `./tasks`)
`--stories, -n <count>`	Number of user stories (template mode only)
`--timeout, -t <ms>`	Timeout for AI agent calls in milliseconds (0 = no timeout, default: 180000)
`--force, -f`	Overwrite existing files

Examples

AI-Powered Chat Mode (Recommended)

Bash

# Start interactive AI conversation
ralph-tui create-prd --chat
 
# Use a specific agent
ralph-tui create-prd --chat --agent opencode

Template Mode

Bash

# Use template wizard (fills in placeholders)
ralph-tui create-prd
 
# Specify number of stories
ralph-tui create-prd --stories 8

Custom Output Location

Bash

# Save PRD to custom directory
ralph-tui create-prd --chat --output ./docs/prds
 
# Overwrite existing PRD
ralph-tui create-prd --chat --force

Disable Timeout

Bash

# Disable timeout for long PRD creation sessions (0 = no timeout)
ralph-tui create-prd --chat --timeout 0
 
# Set custom timeout (in milliseconds)
ralph-tui create-prd --chat --timeout 600000  # 10 minutes

Custom PRD Skill

Use a custom PRD skill from your configured skills_dir:

Bash

# Requires skills_dir in your config file
ralph-tui create-prd --chat --prd-skill my-custom-skill

See Configuration for how to set skills_dir.

PRD Format Requirements for Task Creation

Custom skills must produce PRDs that are compatible with downstream task creation. The generated PRD must include:

User Stories with IDs matching pattern ### US-XXX: Title:

Markdown

### US-001: Add user authentication
 
**As a** registered user
**I want** to log in with email and password
**So that** I can access my account
 
#### Acceptance Criteria
- [ ] Login form displays on /login route
- [ ] Invalid credentials show error message
- [ ] Successful login redirects to dashboard

Quality Gates section (optional but recommended):

Markdown

## Quality Gates
 
These commands must pass for every user story:
- `bun run typecheck` - Type checking
- `bun run lint` - Linting

INFO

If a custom skill generates a PRD without user stories (matching ### US-XXX: pattern), task creation will fail with an error message.

Chat Mode Workflow

When you run create-prd --chat, the AI guides you through:

Feature Goal

What problem does this feature solve? What's the high-level objective?

Target Users

Who will use this feature? What are their needs?

Scope Definition

What should be included? What's explicitly out of scope?

User Stories

The AI helps break down the feature into discrete, implementable stories.

Quality Gates

What commands must pass? (e.g., bun run typecheck, bun run lint)

Task Creation

After generating the PRD, you're asked whether to create tasks:

JSON - Create prd.json for the json tracker
Beads - Create issues in your Beads project
Skip - Just save the PRD Markdown

Output Files

The command creates:

File	Description
`./tasks/prd-<feature-name>.md`	The PRD Markdown document
`./prd.json`	Task file (if JSON selected)

PRD Structure

Generated PRDs follow this structure:

Markdown

# Feature Name
 
## Overview
Brief description of the feature and its goals.
 
## User Stories
 
### US-001: Story Title
**As a** [user type]
**I want** [capability]
**So that** [benefit]
 
#### Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
 
## Quality Gates
 
These commands must pass for every user story:
- `bun run typecheck` - Type checking
- `bun run lint` - Linting
- `bun run build` - Build verification

Quality Gates

Quality gates are critical for successful automation. They tell Ralph what commands must pass after each task.

INFO

Quality gates are extracted from the PRD and automatically appended to each user story's acceptance criteria during conversion.

Common quality gates:

Markdown

## Quality Gates
 
These commands must pass for every user story:
- `bun run typecheck` - Type checking
- `bun run lint` - Linting
- `bun run build` - Build verification
- `bun run test` - Unit tests

Best Practices

Keep Stories Small

Each user story should be completable in one agent session (roughly one context window). If you can't describe it in 2-3 sentences, split it.

Markdown

# Too big - split this
### US-001: Implement user authentication system
 
# Better - separate concerns
### US-001: Add login form component
### US-002: Create authentication API endpoints
### US-003: Implement session management
### US-004: Add logout functionality

Make Criteria Verifiable

Acceptance criteria should be testable, not vague:

Markdown

# Bad - too vague
- [ ] The form looks good
- [ ] Error handling works
 
# Good - specific and testable
- [ ] Form displays validation errors below each invalid field
- [ ] Invalid submission shows error toast with message
- [ ] Network errors display retry button

Order Dependencies

Put foundational stories first:

Markdown

### US-001: Create database schema (no dependencies)
### US-002: Implement backend API (depends on US-001)
### US-003: Build frontend components (depends on US-002)

Troubleshooting

"Agent not responding"

Ensure your agent CLI is working:

Bash

# Test Claude Code
claude --version
 
# Test OpenCode
opencode --version

"Output directory not found"

Create the output directory first:

Bash

mkdir -p ./tasks
ralph-tui create-prd --chat

convert - Convert an existing PRD to tasks
run - Execute tasks from the generated PRD
setup - Install skills for PRD creation