ralph

Files (1)

• SKILL.md

SKILL.md (first lines)

# Ralph — autonomous campaign delivery

Ralph runs an explicitly ordered list of trusted `tk` tickets. Each delivery is
one retained worktree/branch, one recipe run, and one pull request. The next
delivery starts only after Ralph proves that the previous PR merged on a
freshly fetched base branch.

The controller owns pinning, ticket closure, pushes, PR identity, required
checks, merge authority, and durable recovery. The project owns the campaign
manifest, recipe, and prompts.

- CLI/package: `ralph`, `@crcatala/ralph-unpossible`
- Requires Node.js 22+
- Default agent: Pi
- Ticket source: `tk` (`.tickets/`)

Do not guess flags or schema. Prefer `ralph <command> --help`, `ralph guide`,
and the files installed by `ralph init`.

## Pre-flight

Always verify the installed tool and project before changing or running it:

```bash
command -v ralph && ralph --version
ralph guide
ralph config show
ralph doctor
```

Require Ralph `>= 1.0.0`. If it is missing or older, stop and report an
environment mismatch rather than installing an ad hoc global copy that
bypasses your reviewed pin. Fix the environment (image, devcontainer, or
tool-version config) so it provides the reviewed Ralph pin, then verify the
command again.

Run from the repository root. `ralph doctor` must pass its required checks:
Node, Ralph home, project, complete Pi provider/model/thinking configuration,
and Pi's non-inference preflight. GitHub and `tk` checks are reported as
optional by doctor, but are required in practice for an autonomous PR
campaign.

Runtime configuration has no implicit model. Values resolve field-by-field:
CLI (where supported) → `.ralph/config.json` → `$RALPH_HOME/config.json`.
Configure all three values with the actual runtime you intend to use; do not
invent provider or model ids:

```bash
ralph config init --project --provider <actual-provider> --model <actual-model> --thinking <actual-level>
ralph config show
ralph doctor --json
```

Valid thinking levels are `off`, `minimal`, `low`, `medium`, `high`, and
`xhigh`. Use `high`/`xhigh` only when the selected model and provider support
it and cost/latency are acceptable. Credentials belong in the runtime
environment, not committed config.

## Set up a campaign

Install the editable standard recipe and prompts, then scaffold a campaign:

```bash
ralph init
ralph new my-campaign --epic <optional-tk-epic> \
  --ticket <first-ticket> --ticket <second-ticket>
```

`ralph init` is non-destructive: it installs missing files and keeps edited
ones. The project layout is:

```text
.ralph/
  config.json                         # optional project runtime config
  campaigns/<name>/campaign.yaml     # campaign manifest
  recipes/standard-pr.yaml            # editable delivery recipe
  prompts/implement.md               # editable agent prompts
  prompts/review-fix.md
  prompts/verify.md
  prompts/pr-description.md
```

A campaign manifest should look like this:

```yaml
version: 2
name: my-campaign
base_branch: main

source:
  type: tk
  epic: ru-epic                 # optional context only; never auto-closed

recipe: .ralph/recipes/standard-pr.yaml

pull_request:
  branch_template: "ralph/{{campaign}}/{{ticket}}"
  title_template: "{{ticket}}: {{ticket_title}}"
  draft: false

deliveries:                     # order is the dependency model
  - ticket: ru-first
  - ticket: ru-second
```

Only `{{campaign}}`, `{{ticket}}`, and `{{ticket_title}}` are valid template
placeholders. Delivery ticket ids must be unique and path-safe. Keep tickets
small enough for one independently reviewable PR. Ralph never infers,
decomposes, or reorders deliveries.

Before the first run, commit to the campaign `base_branch`:

- the campaign manifest;
- every delivery ticket and optional epic;
- the referenced recipe and all referenced prompts;
- `.ralph/config.json` when the project should pin the runtime selection.

The fetched base commit is the trust boundary. Local edits on a candidate
branch cannot change the active manifest, recipe, prompts, or trusted tickets.

From crcatala/skills, MIT.

More from crcatala/skills