Ralph TUI - Create JSON Tasks

Converts PRDs to prd.json format for ralph-tui autonomous execution.

Note: This skill is bundled with ralph-tui's JSON tracker plugin. Future tracker plugins (Linear, GitHub Issues, etc.) will bundle their own task creation skills.

⚠️ CRITICAL: The output MUST be a FLAT JSON object with "name" and "userStories" at the ROOT level. DO NOT wrap content in a "prd" object or use "tasks" array. See "Schema Anti-Patterns" section below.

The Job

Take a PRD (markdown file or text) and create a prd.json file:

• Extract Quality Gates from the PRD's "Quality Gates" section

• Parse user stories from the PRD

• Append quality gates to each story's acceptance criteria

• Set up dependencies between stories

• Output ready for ralph-tui run --prd <path>

Step 1: Extract Quality Gates

Look for the "Quality Gates" section in the PRD:

Quality Gates

These commands must pass for every user story:

• pnpm typecheck - Type checking
• pnpm lint - Linting

For UI stories, also include:

• Verify in browser using dev-browser skill

Extract:

• Universal gates: Commands that apply to ALL stories (e.g., pnpm typecheck )

• UI gates: Commands that apply only to UI stories (e.g., browser verification)

If no Quality Gates section exists: Ask the user what commands should pass, or use a sensible default like npm run typecheck .

Output Format

The JSON file MUST be a FLAT object at the root level:

{ "name": "[Project name from PRD or directory]", "branchName": "ralph/[feature-name-kebab-case]", "description": "[Feature description from PRD]", "userStories": [ { "id": "US-001", "title": "[Story title]", "description": "As a [user], I want [feature] so that [benefit]", "acceptanceCriteria": [ "Criterion 1 from PRD", "Criterion 2 from PRD", "pnpm typecheck passes", "pnpm lint passes" ], "priority": 1, "passes": false, "notes": "", "dependsOn": [] }, { "id": "US-002", "title": "[UI Story that depends on US-001]", "description": "...", "acceptanceCriteria": [ "...", "pnpm typecheck passes", "pnpm lint passes", "Verify in browser using dev-browser skill" ], "priority": 2, "passes": false, "notes": "", "dependsOn": ["US-001"] } ] }

CRITICAL: Schema Anti-Patterns (DO NOT USE)

The following patterns are INVALID and will cause validation errors:

❌ WRONG: Wrapper object

{ "prd": { "name": "...", "userStories": [...] } }

This wraps everything in a "prd" object. DO NOT DO THIS. The "name" and "userStories" fields must be at the ROOT level.

❌ WRONG: Using "tasks" instead of "userStories"

{ "name": "...", "tasks": [...] }

The array is called "userStories", not "tasks".

❌ WRONG: Complex nested structures

{ "metadata": {...}, "overview": {...}, "migration_strategy": { "phases": [...] } }

Even if the PRD describes phases/milestones/sprints, you MUST flatten these into a single "userStories" array.

❌ WRONG: Using "status" instead of "passes"

{ "userStories": [{ "id": "US-001", "status": "open" // WRONG! }] }

Use "passes": false for incomplete stories, "passes": true for completed.

✅ CORRECT: Flat structure at root

{ "name": "Android Kotlin Migration", "branchName": "ralph/kotlin-migration", "userStories": [ {"id": "US-001", "title": "Create Scraper interface", "passes": false, "dependsOn": []}, {"id": "US-002", "title": "Implement WeebCentralScraper", "passes": false, "dependsOn": ["US-001"]} ] }

Story Size: The #1 Rule

Each story must be completable in ONE ralph-tui iteration (~one agent context window).

Ralph-tui spawns a fresh agent instance per iteration with no memory of previous work. If a story is too big, the agent runs out of context before finishing.

Right-sized stories:

• Add a database column + migration

• Add a UI component to an existing page

• Update a server action with new logic

• Add a filter dropdown to a list

Too big (split these):

• "Build the entire dashboard" → Split into: schema, queries, UI components, filters

• "Add authentication" → Split into: schema, middleware, login UI, session handling

• "Refactor the API" → Split into one story per endpoint or pattern

Rule of thumb: If you can't describe the change in 2-3 sentences, it's too big.

Dependencies with dependsOn

Use the dependsOn array to specify which stories must complete first:

{ "id": "US-002", "title": "Create API endpoints", "dependsOn": ["US-001"], // Won't be selected until US-001 passes ... }

Ralph-tui will:

• Show US-002 as "blocked" until US-001 completes

• Never select US-002 for execution while US-001 is open

• Include "Prerequisites: US-001" in the prompt when working on US-002

Correct dependency order:

• Schema/database changes (no dependencies)

• Backend logic (depends on schema)

• UI components (depends on backend)

• Integration/polish (depends on UI)

Acceptance Criteria: Quality Gates + Story-Specific

Each story's acceptance criteria should include:

• Story-specific criteria from the PRD (what this story accomplishes)

• Quality gates from the PRD's Quality Gates section (appended at the end)

Good criteria (verifiable):

• "Add status column to tasks table with default 'open'"

• "Filter dropdown has options: All, Open, Closed"

• "Clicking delete shows confirmation dialog"

Bad criteria (vague):

• ❌ "Works correctly"

• ❌ "User can do X easily"

• ❌ "Good UX"

• ❌ "Handles edge cases"

Conversion Rules

• Extract Quality Gates from PRD first

• Each user story → one JSON entry

• IDs: Sequential (US-001, US-002, etc.)

• Priority: Based on dependency order (1 = highest)

• dependsOn: Array of story IDs this story requires

• All stories: passes: false and empty notes

• branchName: Derive from feature name, kebab-case, prefixed with ralph/

• Acceptance criteria: Story criteria + quality gates appended

• UI stories: Also append UI-specific gates (browser verification)

Output Location

Default: ./tasks/prd.json (alongside the PRD markdown files)

This keeps all PRD-related files together in the tasks/ directory.

Or specify a different path - ralph-tui will use it with:

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

Example

Input PRD:

PRD: Task Priority System

Add priority levels to tasks.

Quality Gates

These commands must pass for every user story:

• pnpm typecheck - Type checking
• pnpm lint - Linting

For UI stories, also include:

• Verify in browser using dev-browser skill

User Stories

US-001: Add priority field to database

Description: As a developer, I need to store task priority.

Acceptance Criteria:

• Add priority column: 1-4 (default 2)
• Migration runs successfully

US-002: Display priority badge on task cards

Description: As a user, I want to see task priority at a glance.

Acceptance Criteria:

• Badge shows P1/P2/P3/P4 with colors
• Badge visible without hovering

US-003: Add priority filter dropdown

Description: As a user, I want to filter tasks by priority.

Acceptance Criteria:

• Filter dropdown: All, P1, P2, P3, P4
• Filter persists in URL

Output prd.json:

{ "project": "my-app", "branchName": "ralph/task-priority", "description": "Add priority levels to tasks", "userStories": [ { "id": "US-001", "title": "Add priority field to database", "description": "As a developer, I need to store task priority.", "acceptanceCriteria": [ "Add priority column: 1-4 (default 2)", "Migration runs successfully", "pnpm typecheck passes", "pnpm lint passes" ], "priority": 1, "passes": false, "notes": "", "dependsOn": [] }, { "id": "US-002", "title": "Display priority badge on task cards", "description": "As a user, I want to see task priority at a glance.", "acceptanceCriteria": [ "Badge shows P1/P2/P3/P4 with colors", "Badge visible without hovering", "pnpm typecheck passes", "pnpm lint passes", "Verify in browser using dev-browser skill" ], "priority": 2, "passes": false, "notes": "", "dependsOn": ["US-001"] }, { "id": "US-003", "title": "Add priority filter dropdown", "description": "As a user, I want to filter tasks by priority.", "acceptanceCriteria": [ "Filter dropdown: All, P1, P2, P3, P4", "Filter persists in URL", "pnpm typecheck passes", "pnpm lint passes", "Verify in browser using dev-browser skill" ], "priority": 3, "passes": false, "notes": "", "dependsOn": ["US-002"] } ] }

Running with ralph-tui

After creating prd.json:

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

Ralph-tui will:

• Load stories from prd.json

• Select the highest-priority story with passes: false and no blocking dependencies

• Generate a prompt with story details + acceptance criteria

• Run the agent to implement the story

• Mark passes: true on completion

• Repeat until all stories pass

Checklist Before Saving

• Extracted Quality Gates from PRD (or asked user if missing)

• Each story completable in one iteration

• Stories ordered by dependency (schema → backend → UI)

• dependsOn correctly set for each story

• Quality gates appended to every story's acceptance criteria

• UI stories have browser verification (if specified in Quality Gates)

• Acceptance criteria are verifiable (not vague)

• No circular dependencies