| name | riveter-create-run |
| description | Convert a spec into a Ralph the Riveter PRD and run folder for `riveter run`. Triggered by "riveter create run", "create a prd for riveter", "spec out", "plan this feature for riveter", or "convert this spec for riveter". Non-interactive — does not ask follow-up questions. |
Skill: riveter-create-run — Spec → Riveter run folder
You convert a user-supplied spec (free-form description or full PRD markdown)
into a Riveter run folder that the riveter CLI can execute.
You are non-interactive. Do not ask the user clarifying questions. The user
can edit prd.toml after you finish if anything needs tweaking.
Inputs
- A spec (the user's message, or a file/path/URL they reference). Preserve it
verbatim — never paraphrase the original input when saving it.
Output
You will create one folder under the Riveter state directory and print the
runId. The CLI takes it from there.
Steps
1. Determine the state directory
Default: ~/.riveter on every platform. If RIVETER_STATE_DIR is set, use
that instead.
The runs live at <state-dir>/runs/<runId>/ and are never auto-deleted by
Riveter — they persist until the user removes them by hand.
2. Compute the runId
<kebab-of-feature-title>-<random-8-alphanumeric>
- lowercase
[a-z0-9-]+
- total length ≤ 64
- the random 8-char suffix uses
[a-z0-9] to keep runs unique per invocation
Example: task-priority-a1b2c3d4
3. Create the folder and write files
Create <state-dir>/runs/<runId>/ (mkdir -p), then write:
spec.md — the original user input, verbatim. Do not edit it.prd.toml — the structured PRD (schema below)
If the input already contains ## User Stories (or equivalent structured
sections), use those story titles + acceptance criteria directly. Otherwise,
synthesize stories from the description.
prd.toml schema
description = "<one-paragraph project context the agent sees every iteration>"
createdAt = "<ISO-8601 UTC, e.g. 2026-05-24T11:42:07Z>"
[[stories]]
id = 1
title = "<≤ 80 chars; reads well as a commit subject>"
passes = false
notes = ""
acceptanceCriteria = [
"<concrete, testable assertion>",
"<another>",
"<typecheck/test passes>",
]
[[stories]]
id = 2
notes is optional. Leave it as an empty string for fresh PRDs — the agent
may overwrite it with per-story scratch context (failing commands, design
notes, references) so a future iteration on the same story can pick up
where the previous one left off.
Rules to follow:
- One story = one focused commit. Aim for stories small enough that a fresh
agent with no prior context can complete them.
- Title ≤ 80 chars. The CLI rejects longer titles. Trim adjectives, not
meaning.
- Acceptance criteria are testable. Each entry should be checkable by the
agent (file edited, test passing, command exits zero).
passes = false for all stories. The CLI flips them as the agent
completes work.- Sequential
ids (1..N, no gaps). The CLI validates this.
4. Validate
Run:
riveter validate -r <runId>
Parse the output. Each - line under a ✗ heading is a separate error.
If validation fails:
- Read the errors.
- Patch the offending file (almost always
prd.toml — fix title length,
resequence ids, fill empty acceptanceCriteria, etc.).
- Re-run
riveter validate -r <runId>.
- Repeat up to 3 attempts total.
If validation still fails after 3 attempts, show the user the remaining errors
and do not print the "ready to run" message.
5. Print the handoff message
Only after riveter validate exits 0:
Created run <runId> at <state-dir>/runs/<runId>.
Review prd.toml, then run: riveter run -r <runId>
Notes for the agent executing this skill
- You have shell + filesystem access. Use them.
- Do not implement the spec — just convert it into the run folder. The
riveter run step (driven by Codex/Claude/mock) does the actual coding work.
- Do not initialize a jj repo or move files inside the user's project. The
CLI assumes the user is in their own jj repo when they later invoke
riveter run.
