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`.