Feature: PRD Import

Relevant source files

The following files were used as context for generating this wiki page:

• ralph_import.sh
• README.md
• CLAUDE.md
• tests/helpers/fixtures.bash
• create_files.sh
• IMPLEMENTATION_PLAN.md
• CONTRIBUTING.md

The PRD Import feature, executed via the ralph-import command, is a tool designed to bootstrap a new Ralph project from an existing Product Requirements Document (PRD) or specification file. It leverages the Claude Code CLI to intelligently parse the source document and convert it into the structured format required for the Ralph autonomous development loop. This process generates key control files such as PROMPT.md, @fix_plan.md, and specs/requirements.md, making the project immediately ready for autonomous work.

The feature supports a wide range of input formats, including Markdown, plain text, JSON, Word documents, and PDFs. It is a core part of the project's setup workflow, enabling users to quickly translate existing project documentation into an actionable plan for the AI agent.

Sources: ralph_import.sh, README.md

Core Workflow

The ralph-import script follows a sequence of steps to convert a source document into a Ralph project. The process begins with user input, sets up the project structure, invokes the Claude Code CLI for the main conversion task, and concludes by processing the output and verifying the generated files.

This diagram illustrates the high-level workflow of the ralph-import command.

Command-Line Interface

The feature is exposed through the ralph-import command, which is made globally available after running the main install.sh script.

Sources: README.md, CLAUDE.md

Usage

The command accepts one required argument and one optional argument.

ralph-import <source-file> [project-name]

Sources: ralph_import.sh:282-285

Arguments

Argument	Description	Required	Default
source-file	Path to the PRD or specification file. Supports .md, .txt, .json, .docx, .pdf, and other text-based formats.	Yes	N/A
project-name	The name for the new Ralph project directory.	No	Derived from the source-file name (e.g., my-prd.md becomes my-prd).

Sources: ralph_import.sh:281-299, 503-506, README.md

Examples

# Convert a markdown PRD and specify a project name
ralph-import product-requirements.md my-app

# Convert a text file and let Ralph auto-name the project
ralph-import requirements.txt

Sources: README.md, ralph_import.sh:286-289

Conversion Process

The core of the feature is the convert_prd function, which orchestrates the interaction with the Claude Code CLI.

Sources: ralph_import.sh:304-488

Prompt Generation

Before calling the AI, the script constructs a detailed prompt in a temporary file (.ralph_conversion_prompt.md). This prompt consists of two parts:

1. A static template: This template instructs the AI on its task: to analyze a PRD and generate three specific output files (PROMPT.md, @fix_plan.md, specs/requirements.md).
2. The user's source document: The content of the user-provided <source-file> is appended to the prompt, providing the context for the conversion.

Sources: ralph_import.sh:332-421

Claude CLI Interaction

The script executes the Claude Code CLI, piping the generated prompt as standard input. It utilizes modern CLI features for enhanced reliability and structured data exchange.

This sequence diagram shows the interaction between the script and the Claude Code CLI.

Modern CLI Integration & JSON Parsing

The ralph-import script is designed to leverage modern features of the Claude Code CLI (version 2.0.76 and higher) for more robust and predictable behavior. It includes a fallback mechanism for backward compatibility.

Sources: ralph_import.sh:11, 248-278, CLAUDE.md

Version Check

The check_claude_version() function is called to determine if the installed CLI meets the minimum version requirement. This check determines whether to use the modern JSON-based workflow or the legacy text-based one.

Sources: ralph_import.sh:248-278

Modern CLI Configuration

When a compatible CLI version is detected, the following configuration is used:

Parameter	Value	Purpose
CLAUDE_OUTPUT_FORMAT	json	Instructs the CLI to return a structured JSON response.
CLAUDE_ALLOWED_TOOLS	Read, Write, Bash(mkdir:*), Bash(cp:*)	Grants the AI specific, limited permissions to perform file operations without interactive prompts.
CLAUDE_MIN_VERSION	2.0.76	The minimum version required for these features.

Sources: ralph_import.sh:8-12

Response Processing

The script uses a two-step process to handle the CLI's output.

This flowchart shows the logic for detecting and parsing the response format.

JSON Parsing (parse_conversion_response)

If the output is valid JSON, the parse_conversion_response function is called. It uses jq to extract key information from the response and populates a set of global variables for later use.

Global Variable	JSON Path (examples)	Description
PARSED_RESULT	.result or .summary	The summary text of the conversion result.
PARSED_SESSION_ID	.sessionId or .session_id	The session ID for potential continuation.
PARSED_FILES_CHANGED	.metadata.files_changed	The number of files modified by the AI.
PARSED_HAS_ERRORS	.metadata.has_errors	A boolean flag indicating if errors occurred.
PARSED_COMPLETION_STATUS	.metadata.completion_status	The status of the task (e.g., "complete", "failed").
PARSED_ERROR_MESSAGE	.metadata.error_message	A specific error message if the conversion failed.
PARSED_ERROR_CODE	.metadata.error_code	An error code associated with a failure.
PARSED_FILES_CREATED	.metadata.files_created	A JSON array of files the AI reported creating.
PARSED_MISSING_FILES	.metadata.missing_files	A JSON array of files the AI expected but were not found.

Sources: ralph_import.sh:122-192

Generated Artifacts

The primary goal of the import process is to generate a set of structured files that form the basis of a new Ralph project.

Sources: ralph_import.sh:343-399

The following diagram shows the structure of the generated project.

File	Description
PROMPT.md	Contains the main development instructions for the Ralph agent, derived from the PRD's goals and objectives.
@fix_plan.md	A prioritized to-do list, converting the PRD's features into actionable, check-list items for the agent.
specs/requirements.md	A detailed technical specification document, preserving technical details from the source PRD like architecture, data models, and APIs.

Sources: ralph_import.sh:343-399, create_files.sh

File Verification and Error Handling

After the Claude Code CLI finishes, the script verifies that the expected files were created. It uses a combination of information from the parsed JSON response (if available) and direct filesystem checks.

• If the PARSED_FILES_CREATED JSON array is available, the script iterates through it to build an initial list of created files.
• It then performs a filesystem check for all expected files (PROMPT.md, @fix_plan.md, specs/requirements.md) to create a definitive list of what exists and what is missing.
• Any discrepancies or missing files are reported to the user with a WARN level log message, ensuring the user is aware of any partial or failed conversions.

Sources: ralph_import.sh:453-488

Conclusion

The PRD Import feature is a critical onboarding tool for the Ralph for Claude Code project. By automating the conversion of human-readable documents into a machine-actionable project structure, it significantly lowers the barrier to entry for starting new autonomous development tasks. Its use of modern CLI features like JSON output and its robust fallback mechanisms demonstrate a commitment to both reliability and backward compatibility. This feature embodies the project's goal of streamlining the interface between human requirements and AI-driven implementation.

Sources: README.md, CLAUDE.md, ralph_import.sh