How PRD Mode Works in Ralph with the --prd Flag and User Stories in oh-my-codex

Ralph's PRD mode activates when you append the --prd flag to the CLI, triggering a workflow that extracts your task description, runs a mandatory deep-interview, generates canonical artifacts in .omx/plans/ and .omx/state/, and breaks requirements into trackable user stories that feed the persistence loop.

The oh-my-codex repository implements a structured AI-driven development cycle through the Ralph CLI. When you invoke PRD mode in Ralph with the --prd flag, the system converts natural language requirements into formal product specifications with acceptance criteria, creating the foundation for iterative, verifiable implementation.

Detecting and Extracting the PRD Task

When Ralph receives the --prd or --PRD flag, the CLI immediately enters PRD mode and extracts your requirements from the remaining arguments.

The normalizeRalphCliArgs function strips the flag and any value assignment from the argument array (lines 79‑95 of src/cli/ralph.ts). Whether you use --prd "description" or --prd="description" syntax, the parser removes the flag and leaves only the raw task text. Subsequently, extractRalphTaskDescription captures this remaining text to serve as the primary task input (lines 76‑79). If you provide an approved plan instead of an explicit task, Ralph extracts the embedded description from that plan.

# Basic invocation—the text after --prd becomes the PRD description

omx ralph --prd "Implement a todo‑app with React + TypeScript"

# Alternative syntax with equals sign

omx ralph --prd="Add a CLI to export CSV reports"

Creating Canonical PRD and Progress Artifacts

Before writing any files, Ralph mandates a deep-interview quick mode session to flesh out requirements. This gate is documented in the skill specification (skills/ralph/SKILL.md lines 88‑92) and enforced by unit tests in src/cli/__tests__/ralph-prd-deep-interview.test.ts. Only after this interview completes does Ralph generate two critical artifacts:

• PRD markdown file: Written to .omx/plans/prd-{slug}.md, containing the structured requirements and user stories.
• Progress ledger: A JSON file at .omx/state/{scope}/ralph-progress.json that tracks iteration state and completion flags.

The CLI populates the mode state with the canonical PRD path via updateModeState (lines 200‑202 of src/cli/ralph.ts), handling migration from legacy file locations if necessary.

// Internal artifact creation flow
await writeRalphSessionFiles(process.cwd(), task, { 
  noDeslop: false, 
  approvedHint: null 
});
// Creates .omx/plans/prd-<slug>.md and .omx/ralph/changed-files.txt

Breaking PRDs into Independent User Stories

After creating the markdown file, Ralph parses the PRD description into a JSON array of user stories following the classic "As a … I want … so that …" pattern. Each story object includes:

• Acceptance criteria: Specific conditions that must be met
• Priority: Numerical ranking for execution order
• passes flag: Boolean indicating verification status

These stories are stored within the PRD file and serve as the task list for the persistence loop (step 7 of the PRD workflow in skills/ralph/SKILL.md). The loop continues iterating through parallel delegation and verification until every story's passes flag is true and architect verification succeeds.

# PRD: Build a todo app

## Description

Implement a todo‑app with React and TypeScript.

## User Stories

- **US‑001** – As a **developer**, I want a **list view** so that I can **see all tasks**.
  - Acceptance: renders list, passes type‑check, tests pass.
  - Priority: 1
  - Passes: false

- **US‑002** – As a **user**, I want to **add a new task** so that I can **track work**.
  - Acceptance: input adds item, UI updates, tests pass.
  - Priority: 2
  - Passes: false

The Persistence Loop and Optional Deslop Pass

Once artifacts are created, Ralph calls startMode('ralph', …) to begin the standard iteration cycle. The loop processes user stories through parallel delegation and verification stages. By default, Ralph includes a final deslop pass (step 7.5) that runs the ai-slop-cleaner tool to remove boilerplate and improve code quality.

You can disable this cleanup phase using the --no-deslop flag (handled at line 22 of src/cli/ralph.ts). When disabled, Ralph skips the mandatory cleanup and continues using the most recent successful pre-deslop verification evidence.

# Skip the final deslop pass

omx ralph --prd "Refactor auth flow" --no-deslop

Summary

• PRD mode activates via the --prd or --PRD flag followed by a natural language task description.
• normalizeRalphCliArgs (lines 79‑95) strips the flag while extractRalphTaskDescription (lines 76‑79) captures the requirements text.
• A mandatory deep-interview quick mode runs before any file system writes to refine requirements.
• Ralph creates .omx/plans/prd-{slug}.md for the specification and .omx/state/{scope}/ralph-progress.json for state tracking.
• The PRD breaks into user stories with acceptance criteria, priority levels, and passes flags that drive the work queue.
• The --no-deslop flag optionally disables the final ai-slop-cleaner verification pass.

Frequently Asked Questions

What happens if I invoke --prd without providing a task description?

Ralph expects either an explicit task string after the flag or an approved plan containing an embedded task. If neither is present, extractRalphTaskDescription will not find a valid input, and the CLI will typically error out or prompt for clarification before entering the persistence loop.

Where does Ralph store the generated PRD files and user stories?

According to the state contract in docs/contracts/ralph-state-contract.md, Ralph writes the canonical PRD markdown to .omx/plans/prd-{slug}.md and the JSON progress ledger to .omx/state/{scope}/ralph-progress.json. These paths are managed by updateModeState in src/cli/ralph.ts (lines 200‑202).

Why is the deep-interview quick mode mandatory in PRD mode?

The skill specification in skills/ralph/SKILL.md (lines 88‑92) mandates this gate to ensure requirements are sufficiently detailed before artifact creation. The corresponding unit test in src/cli/__tests__/ralph-prd-deep-interview.test.ts enforces that Ralph cannot proceed to file generation until this interview step completes successfully.

How does Ralph determine when all user stories are complete?

Each user story object in the JSON task list contains a passes boolean flag. The persistence loop continues iterating through verification and delegation cycles until every story's passes flag is set to true and the architect verification stage succeeds. Only then does Ralph exit the PRD workflow.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}