# Riveter Create Run

> 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: `rivet-dev/riveter-create-run` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rivet-dev/riveter-create-run`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rivet-dev/riveter-create-run/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: rivet-dev (https://skillmd.com/u/rivet-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rivet-dev/riveter-create-run

---


# 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

```toml
description = "<one-paragraph project context the agent sees every iteration>"
createdAt   = "<ISO-8601 UTC, e.g. 2026-05-24T11:42:07Z>"

[[stories]]
id    = 1                            # 1-indexed, sequential, no gaps
title = "<≤ 80 chars; reads well as a commit subject>"
passes = false                       # always false in fresh PRDs
notes  = ""                          # optional; agent may write scratch notes here
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 `id`s (1..N, no gaps).** The CLI validates this.

### 4. Validate

Run:

```sh
riveter validate -r <runId>
```

Parse the output. Each `- ` line under a `✗` heading is a separate error.

If validation fails:

1. Read the errors.
2. Patch the offending file (almost always `prd.toml` — fix title length,
   resequence ids, fill empty `acceptanceCriteria`, etc.).
3. Re-run `riveter validate -r <runId>`.
4. 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`.