The Action

The path an issue takes

Two of these five stages are seams you can swap. The rest is plumbing Ralph owns.

1. 1

   Issue labeled ready-for-agent

   Ralph defines no label of its own. It reuses the one your triage flow already produces, which also posts an Agent Brief — the structured comment Ralph treats as the contract.

2. 2

   A runner claims it

   Any machine registered to the repo. One agent per issue, enforced by a concurrency group keyed on the issue number.

3. 3

   Install the pinned skill pack

   seam · skills-repo · skills-ref

   Defaults to mattpocock/skills at a pinned tag. Cloned, copied into the workspace, then excluded via .git/info/exclude so it never lands in the agent's diff. Point it at your own pack and the rest of the pipeline is unchanged.

4. 4

   Agent runs the entry skill

   seam · agent · agent-args

   The AFK preamble is prepended, then the brief. The pack owns iteration, testing and the definition of done — Ralph only holds the wall clock.

5. 5

   Draft PR, back on the thread

   ASSUMPTIONS.md lands in the PR body. Blocked runs, blown budgets and failed verification all ship as drafts that say why.

A line down the middle

Running interactive skills unattended

This is the interesting problem. The pack's skills assume a human is in the room — one of them refuses to write a test at a seam you have not confirmed. On a runner there is nobody to ask, so a naive run either stalls or quietly invents an answer and never mentions it.

ASSUMPTIONS.md then lands in the PR body, so review opens with every judgment call made without you. Ambiguity gets an assumption. A genuine block — a product decision, a missing credential — gets BLOCKED.md and a stop, which Ralph turns into a draft PR carrying the question.

Unattended is the default, not the only mode. With session: herdr, the agent works interactively in a session a person can join. Ralph posts the join command on the issue, and the session stays up after the pull request opens.

Defaults in the box, nothing welded shut

Ralph ships pointed at a real skill pack and a real agent, so the zero-config path works on day one. Neither is baked in. Both are inputs, and changing either is one line of YAML.

# what you get without configuring anything
skills-repo: mattpocock/skills
skills-ref:  v1.1.0
agent:       claude

The pack is the bigger lever of the two. It decides how work gets planned, where tests go, and when something is done — so pointing skills-repo at your own pack changes how every agent behaves without changing a line of the orchestrator.

Your own skills, on top

You do not have to choose between the pack and skills of your own. Three sources reach the agent, and only the middle one is pinned.

1. Your repo

   wins

   Anything committed under .claude/skills or .agents/skills. On a name collision the repo wins and the pack is skipped — a skill you committed is a deliberate override, so it is left alone.

2. The pack

   pinned

   Cloned at the ref you named and copied in around whatever your repo already defines. It fills the gaps rather than replacing the set.

3. The runner

   not pinned

   Agents also read skills under $HOME on the machine, so whatever the person who set that runner up has installed is in scope. This is the layer Ralph cannot pin, and the first place to look when two runners disagree.

Agents

An adapter is one file implementing a three-part contract. Adding an agent never touches the orchestrator.

• claude
• codex
• opencode
• pi

AGENT_COMMITS=true|false   # does the agent commit its own work?

agent_preflight()          # exit non-zero with a fixable message if the
                           # CLI is missing or unauthenticated

agent_run <prompt_file>    # run to completion against $PWD, non-interactive
                           # must forward "${AGENT_ARGS_ARR[@]}"

pi is the one worth calling out. It already reads .agents/skills — the same path this action installs packs into — so a pack drops in with no special-casing at all. It is also multi-provider, which makes it the one adapter where bring-your-own-agent extends to bring-your-own-model.

Traps worth knowing about

Every one of these was caught by testing rather than reading. They share a shape: the failure exits zero.

• pi silently runs with no skills

  exits 0

  In non-interactive modes pi never prompts for trust — it falls back to defaultProjectTrust, which defaults to ask, and ask ignores project-local resources. An installed skill pack is a project-local resource. Without --approve you get a plausible pull request built from none of the workflow, and nothing in the log says so. The adapter always passes it.

• An absent agent brief looked present

  1 byte

  jq writes a trailing newline even for an empty result, so the brief file was never zero-length and the emptiness check always passed. Every unbriefed issue would have claimed a contract it did not have. The check now tests for non-whitespace content.

• Passthrough flags vanished at the boundary

  silently dropped

  timeout(1) needs a command, so the adapter function is serialized into a subshell — and arrays are not exported. Model and provider flags were being dropped on exactly the path that runs in production. The array is now serialized alongside the function, verified identical on both sides.

• macOS runners still ship bash 3.2

  unbound variable

  Expanding an empty array under set -u aborts the run on bash 3.2, which is what /bin/bash still is on a current Mac. Every adapter guards the expansion. The same machines have no timeout(1) at all, so the budget falls back to the job-level timeout and says so in the log.

• CI will not run on Ralph's pull requests

  by design

  GitHub does not trigger pull_request workflows for pull requests opened with the default token, to prevent recursion. Left alone, the agent's work would be the only work arriving unchecked. Pass a PAT or App token to get CI back.

• New repos will not let Actions open a pull request

  after the push

  "Allow GitHub Actions to create and approve pull requests" is off by default, and pull-requests: write does not override it. The first real run did ten minutes of good work, pushed the branch, and died at gh pr create — the issue still said only "picked this up" and the drafted PR body was gone. The default token cannot read the setting, so preflight can usually only warn; a failed PR now leaves the branch, a compare link and the fix on the issue, and the body in the job summary.

What is in the package

action.yml

Composite manifest — 12 inputs, 3 outputs

scripts/ralph.sh

Intake, branch, prompt, run, assess, ship

scripts/install-skills.sh

Pinned pack install, kept out of the diff

scripts/afk-preamble.md

Converts interactive gates into recorded decisions

scripts/agents/*.sh

One file per agent, three-part contract

examples/ralph.yml

The workflow you copy into your repo