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:

{

  "name": "Task Priority System",

  "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