convert | Ralph TUI

Synopsis

Bash

ralph-tui convert [options] <prd-file>

The convert command transforms a PRD markdown file into a task format that Ralph can execute. It extracts user stories, acceptance criteria, and quality gates to create structured task files.

INFO

If you used create-prd --chat, you were likely already prompted to convert to tasks. Use this command when you have an existing PRD that needs conversion.

Options

Option	Description
`--to <format>`	Target format: `json`
`--output, -o <path>`	Output file path (default: `./prd.json`)
`--branch, -b <name>`	Git branch name (prompts if not provided)
`--force, -f`	Overwrite existing files

Arguments

Argument	Description
`<prd-file>`	Path to the PRD markdown file to convert

Examples

Basic Conversion

Bash

# Convert PRD to prd.json
ralph-tui convert ./tasks/prd-my-feature.md
 
# Specify output path
ralph-tui convert ./tasks/prd-my-feature.md --output ./my-tasks.json

Explicit Format

Bash

# Convert to JSON format
ralph-tui convert --to json ./tasks/prd-my-feature.md

Overwrite Existing

Bash

# Force overwrite of existing prd.json
ralph-tui convert --force ./tasks/prd-my-feature.md

With Git Branch

Bash

# Specify branch name for beads integration
ralph-tui convert --branch feat/my-feature ./tasks/prd-my-feature.md

Conversion Process

When you run convert, the command:

Parse PRD

Reads the markdown file and extracts:

Feature title and description
User stories with their IDs
Acceptance criteria for each story
Dependencies between stories

Extract Quality Gates

Finds the "## Quality Gates" section and extracts commands that must pass.

Append Gates to Stories

Adds quality gate commands to each story's acceptance criteria, ensuring every task runs the required checks.

Generate Output

Creates the task file in the specified format with proper structure for Ralph to execute.

Output Format

JSON (prd.json)

The JSON output follows this structure:

JSON

{
  "title": "My Feature",
  "description": "Feature description from PRD",
  "stories": [
    {
      "id": "US-001",
      "title": "First user story",
      "description": "As a user, I want...",
      "acceptanceCriteria": [
        "Criterion from PRD",
        "Another criterion",
        "bun run typecheck passes",
        "bun run lint passes"
      ],
      "dependsOn": [],
      "passes": false
    },
    {
      "id": "US-002",
      "title": "Second user story",
      "dependsOn": ["US-001"],
      "passes": false
    }
  ]
}

INFO

The passes: false field indicates the task hasn't been completed. Ralph sets this to true when the task is done.

Quality Gate Integration

Quality gates from the PRD are automatically appended to acceptance criteria:

PRD Input:

Markdown

### US-001: Add login form
 
#### Acceptance Criteria
- [ ] Form has email and password fields
- [ ] Submit button is disabled until valid
 
## Quality Gates
- `bun run typecheck` - Type checking
- `bun run lint` - Linting

JSON Output:

JSON

{
  "id": "US-001",
  "acceptanceCriteria": [
    "Form has email and password fields",
    "Submit button is disabled until valid",
    "bun run typecheck passes",
    "bun run lint passes"
  ]
}

Dependency Detection

The converter attempts to detect dependencies from:

Explicit "depends on" mentions in the PRD
Prerequisites sections in user stories
Story ordering (later stories may depend on earlier ones)

You can also manually add dependencies in the PRD:

Markdown

### US-003: Build frontend form
**Prerequisites**: US-001 (schema), US-002 (API)

Workflow Example

Create PRD

Write or generate a PRD markdown file:

Bash

ralph-tui create-prd --chat
# Save as ./tasks/prd-auth.md

Review PRD

Open and review the PRD, adjusting stories and criteria as needed.

Convert to Tasks

Bash

ralph-tui convert ./tasks/prd-auth.md

Run Ralph

Bash

ralph-tui run --prd ./prd.json

Troubleshooting

"No user stories found"

Ensure your PRD uses the expected format:

Markdown

### US-001: Story Title
or
### User Story 1: Story Title

"Quality gates section not found"

Add a quality gates section to your PRD:

Markdown

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

"Output file exists"

Use --force to overwrite, or specify a different output path:

Bash

ralph-tui convert --force ./tasks/prd-auth.md
# or
ralph-tui convert ./tasks/prd-auth.md --output ./new-tasks.json

create-prd - Create a new PRD with AI assistance
run - Execute tasks from the converted file
status - Check execution progress