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

> Discover how Ralph's PRD mode and --prd flag work in oh-my-codex. Learn to generate artifacts and break requirements into user stories for efficient development.

- Repository: [Bellman/oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- Tags: how-to-guide
- Published: 2026-04-03

---

**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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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.

```bash

# 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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/skills/ralph/SKILL.md) lines 88‑92) and enforced by unit tests in [`src/cli/__tests__/ralph-prd-deep-interview.test.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/cli/ralph.ts)), handling migration from legacy file locations if necessary.

```ts
// 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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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.

```markdown

# 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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/cli/ralph.ts)). When disabled, Ralph skips the mandatory cleanup and continues using the most recent successful pre-deslop verification evidence.

```bash

# 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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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.