prd-to-tasks

name

prd-to-tasks

description

Break down a PRD.md into a concrete, executable `tasks.md` checklist that a developer or an AI agent can pick up and ship. Reads `.workflow/PRD.md` (and `.workflow/PROJECT.md` for context), produces `.workflow/tasks.md` with one task per checkable bullet, grouped by user story or epic, sized to ~2–8 hours each. Output is compatible with beads, GitHub Issues import, `linear-scrum` (via Linear MCP), and ralph-tui task sources. Use when the user says "split this into tasks", "make the issues", "ticket the PRD", "task breakdown", "create the issues from the PRD", or the orchestrator routes here from phase `prd_drafted`. Not for: writing code or implementing the tasks (those run later).

prd-to-tasks — PRD.md → executable task list

This skill turns a PRD into a flat, ordered list of tasks small enough to be picked up by a developer or an AI executor. The output is .workflow/tasks.md — Markdown with - [ ] checkboxes — designed to be:

• Readable by humans as a project punch-list.
• Importable into beads (the gstack convention), GitHub Issues (one task per issue), or fed to ralph-tui as the task source.
• Pushable to Linear via the linear-scrum skill (Setup mode), which reads tasks.md through the Linear MCP and creates one issue per task — not a CSV import.
• Atomic enough that each line items represents 2–8 hours of work for a typical developer (or one focused session for an AI agent).

When this skill applies

• A .workflow/PRD.md exists and phase is prd_drafted.
• The user asks to "make the issues", "split the PRD", "create the task list", "ticket this".
• The orchestrator routes here from prd_drafted (optional next step before scaffolding).

If .workflow/tasks.md already exists, enter revise mode: read the existing tasks and propose specific edits (add, remove, re-order, re-size) rather than overwriting.

Contract

This skill follows the dev-flow contract — see references/contracts.md for the canonical schema. Key facts:

• Reads <root>/.workflow/PRD.md (mandatory) and .workflow/PROJECT.md (for stack/audience context).
• Writes <root>/.workflow/tasks.md.
• Sets phase = "tasks_split" on success (only if current phase is earlier in the enum).

Workflow

Step 1 — Read inputs and decide structure

Read .workflow/PRD.md. Extract:

• The list of user stories (As a … I want … so that …).
• The acceptance criteria for each story.
• Any non-goals (these become negative tasks: explicit "do NOT do X" notes, not work items).
• Technical constraints (e.g., "must use Postgres" → tasks like "set up Drizzle + Neon" go on the list early).

Group tasks into epics when there are 3+ user stories. With fewer stories, keep a flat list.

Step 2 — Decompose each user story into tasks

For each user story, ask: "What must exist for the acceptance criteria to be true?" Walk down from there:

1. Data layer — DB schemas, migrations, seed data.
2. API / server logic — endpoints, server actions, validation, auth checks.
3. UI — pages/routes, components, states (loading/empty/error).
4. Auth & permissions — who can access this, what guards exist.
5. Telemetry & error handling — logging, error boundaries, user-visible errors.
6. Tests — unit + integration where applicable; explicit task even if "smoke test only".

Skip layers the story doesn't actually need. A purely UI story doesn't need a DB task.

Sizing target: each task ≈ 2–8 hours of focused work. If a task feels bigger, split. If a task is < 1 hour, merge with a sibling.

Title convention: imperative verb first ("Add user-settings page", "Wire login flow", "Set up Drizzle schema for posts"). Avoid "Implement X" — too vague.

Step 3 — Write tasks.md

Use this exact format:

# <Project Name> — Tasks

> Generated by `prd-to-tasks` from PRD.md on <ISO date>. Compatible with beads, GitHub Issues import, `linear-scrum` (via Linear MCP), ralph-tui task source.

## Setup

- [ ] **Set up Next.js + shadcn scaffold** *(addressed by `design-md-to-app`)*
- [ ] **Configure Drizzle + Neon** *(addressed by `module-add db`)*
- [ ] **Wire better-auth + email/password** *(addressed by `module-add auth`)*

## Epic: <user-story name or epic title>

### US-1: As a <persona>, I want <action>, so that <outcome>

- [ ] **<Imperative title>** — <one-sentence body>
  - Acceptance: <bulleted criteria pulled from PRD>
  - Files likely touched: `<best-guess paths>`
 Estimated: <2-8h>
 [ ]  — …



…



 
 



 

Rules:

• One ## Epic: heading per epic, one ### US-N: per user story.
• One - [ ] per concrete task. Sub-bullets under it are details, not separate tasks.
• The *(addressed by …)* annotation marks tasks that are owned by another dev-flow skill — the user (or orchestrator) doesn't have to write code for these, just invoke the right skill. Always tag scaffolding/setup tasks with which skill owns them.
• Order: Setup first (foundation), then epics in priority order from the PRD.
• Don't enumerate [ ] checkboxes for sub-bullets — they're details, not actionable items.
• The - [ ] **<Title>** — <body> format (with the em-dash — separator) is load-bearing. linear-scrum/scripts/task_key.py parses each task line with split(" — ")[0] to derive the title it hashes for dedup (meta.json#linear.issue_map). Do not swap the em-dash for a hyphen, colon, or any other separator — doing so breaks re-run idempotency in linear-scrum.

Step 4 — Update state and report

Update .workflow/meta.json:

• if current phase is earlier than tasks_split, set phase = "tasks_split"
• bump updated_at
• append history:

  {
    "skill": "prd-to-tasks",
    "ran_at": "<now>",
    "outputs": ["tasks.md"],
    "phase_before": "<prev>",
    "phase_after": "tasks_split"
  }
  

Tell the user:

• Number of epics + tasks generated.
• Any open questions still flagged.
• Next-step proposal: usually figma-to-design-md (if not yet run and Figma exists) or design-md-to-app (if DESIGN.md is in place), or linear-scrum (Setup) if they want to run the project as agile scrum in Linear.

If the user wants to move tasks into beads/GitHub Issues/Linear, point at the file — it's already in the right shape. They can use gh issue create per task, ralph-tui-create-beads / ralph-tui-create-json skills if installed, or invoke linear-scrum (Setup mode) to push tasks.md into Linear via MCP — not a CSV import.

Important constraints

• Don't invent acceptance criteria. If the PRD doesn't specify them for a story, ask the user before writing tasks for that story. A task with vague acceptance is worse than no task.
• Don't generate a 100-task list from a 3-story MVP. If the math gives you more than ~15 tasks, you're over-decomposing. Merge.
• Don't include tasks for non-goals. They're explicitly out of scope. List them under ## Non-goals so they stay visible but not actionable.
• Tag setup tasks with the owning skill. "Set up auth" should always say *(addressed by module-add auth)* — this is the bridge between the task list and the skill ecosystem.
• One file, one project. Don't shard tasks.md across multiple files.