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                            # 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 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:

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.