README Setup: Option 3 (Marketplace) appears to be a full alternative to Option 1, but isn't

[luisanton-io]

The confusion

The README presents three setup options as if they're interchangeable alternatives:

• Option 1: Copy to your project
• Option 2: Install skills globally
• Option 3: Use as Claude Code Marketplace

Reading this, it's natural to assume picking Option 3 gives you a complete setup. But it actually only installs the /prd and /ralph converter skills - it doesn't install the ralph.sh runner, prompt.md, or CLAUDE.md into your project.

After doing Option 3, there's no obvious way to actually run Ralph. You still need to do Option 1 to copy ralph.sh + the prompt files into your project, but the README doesn't mention this.

Adding to the confusion: the marketplace plugin package actually includes ralph.sh, prompt.md, and CLAUDE.md alongside the skills. So after installing via Option 3, these files exist on disk inside ~/.claude/plugins/cache/ - which makes it look like the install handled everything. But the plugin system only surfaces the two converter skills; the runner files just sit there unused. It could be expected that the plugin scaffolded them into the project automatically.

What happened in practice

I installed via Option 3, assumed I was done, and confused about how to run it, ended up pointing an alias directly at the cached ralph.sh inside ~/.claude/plugins/cache/. It worked, but prd.json and progress.txt ended up in the plugin cache directory instead of in my project — causing confusion about where state files live and making archiving unreliable. Although it might have been a hasty setup on my end, I would assume this might have happened to someone else.

Suggestion

It could help to clarify and restructure the setup into two sections:

1. Install the runner (required) — currently Option 1 or 2

This installs the ralph.sh runner and the prompt template into your project.

2. Install the converter skills (optional) — currently Option 3

This installs the /prd and /ralph skills for converting PRDs to prd.json format.

This clarifies that copying ralph.sh and the prompt template into your project is still required to actually run the agent loop.

Thanks for the great tool