ralphy-prd skill

SKILL.md

name	description	argument-hint
ralphy-prd	Generate a Ralphy PRD in YAML format. Use when the user asks to create a PRD, task list, or backlog for ralphy execution.	<feature or project description>

Ralphy YAML PRD Generator

Generate execution-ready PRD files in YAML format for use with ralphy --yaml <file>.

Preflight Checks

Before doing anything else, verify the current directory is ready for ralphy:

1. Check if the directory is a git repository (look for a .git directory).
2. Check if a .ralphy directory exists.

If either check fails, stop and tell the user what's missing:

• No .git → "This directory isn't a git repository. Run git init first."
• No .ralphy → "Ralphy hasn't been initialized here. Run ralphy --init first."

Do not generate a PRD until both checks pass.

Workflow

1. Gather context. Ask the user what they want to build or accomplish. Confirm:

   • Objective / feature description
   • Target stack and framework (if not obvious from the codebase)
   • Key constraints or boundaries
   • Definition of done

   If the user provides a short description, state your assumptions and proceed. Only ask clarifying questions when critical information is missing.

2. Decompose into micro-tasks. Break the work into the smallest independently completable units:

   • One logical change per task
   • Each task is independently understandable (an AI agent with no prior context can execute it)
   • Titles are specific, unique, and use imperative verbs: Add, Create, Implement, Refactor, Test, Configure
   • Put acceptance criteria and file-scope hints in the description field

3. Assign parallel groups. Group independent tasks for concurrent execution:

   • Sequential tasks: omit parallel_group (or set to 0)
   • Independent tasks: assign the same non-zero parallel_group number
   • Number groups in dependency order: 1, 2, 3, ...
   • Only parallelize tasks that do NOT edit the same files or domain layer
   • Always follow parallel groups with a sequential integration/verification task

4. Validate. Before outputting:

   • No duplicate titles
   • Every task is actionable and testable
   • Testing and verification tasks are included
   • Final task is a smoke test or verification step

5. Write the file. Output the PRD as a .yaml file in the project root (or user-specified path).

YAML Schema

tasks:
  # Sequential task (no parallel_group or parallel_group: 0)
  - title: "Imperative verb + specific deliverable"
    completed: false
    description: |
      Acceptance criteria and scope details.
      Files to create/modify: path/to/file.go
      Commands to verify: go test ./...

  # Parallel group — independent tasks that can run concurrently
  - title: "Task A in parallel group"
    completed: false
    parallel_group: 1
    description: |
      Details for task A.

  - title: "Task B in parallel group"
    completed: false
    parallel_group: 1
    description: |
      Details for task B.

Field Reference

Field	Type	Required	Notes
title	string	yes	Unique imperative task title
completed	boolean	yes	Always false for new PRDs
parallel_group	integer	no	0 or omitted = sequential. Same non-zero value = run concurrently
description	string	no	Acceptance criteria, file scope, verification commands

Parallelization Heuristics

Good parallel candidates:

• Backend schema setup + UI shell creation
• Independent API endpoint scaffolding
• Test harness setup + docs updates
• Non-overlapping feature modules

Always keep sequential:

• Setup/init tasks (first)
• Integration tasks (after parallel groups)
• Final smoke test / verification (last)

Task Title Conventions

• Start with an imperative verb
• Be specific: Create user login API endpoint not Implement auth
• One deliverable per title
• Keep under 80 characters

Final Notification Task

Every PRD must end with a task that sends a completion notification to the NTFY instance. This is always the very last task (after smoke tests) and is always sequential.

The message must be written for text-to-speech (TTS) — natural spoken language, no abbreviations, no special characters, no markdown. Summarize what the PRD accomplished in a single conversational sentence.

- title: "Send completion notification to NTFY"
  completed: false
  description: |
    Send a TTS-friendly completion message to the NTFY notification service.
    Run: curl -d "All tasks for <project name> are complete. <brief summary of what was done>." http://ntfy.sh/notifications

Examples of good TTS messages:

• "All tasks for the user dashboard are complete. Authentication, API endpoints, and unit tests have been added."
• "The database migration PRD is finished. Schema changes, seed data, and rollback scripts are all in place."
• "Work on the checkout flow is done. Cart, payment integration, and end to end tests are ready."

Output Rules

• Default filename: prd.yaml in the project root
• All completed fields set to false
• Include a comment header with project name and usage instructions
• Keep descriptions concise — bullet points over prose
• Always end with the NTFY notification task as the very last task