Outrider run modes

Outrider can select a candidate for a repository or run against a change you specify.

Automatic selection

Outrider reviews available candidates and repository context, then chooses whether a change is ready to implement.

Pinned change

Use the documented input or command to request a specific method or research item.

Prepared example

Studio’s Quickstart can start from a prepared implementation branch. This demonstrates the review-and-refine workflow and can finish faster than an implementation from scratch.

Outcomes

A run may produce a draft PR, Issue, branch, or a decision not to publish. Use the GitHub Actions log to inspect the outcome and checks.

Exact inputs

The tables below define each supported run mode and its configuration.

Ways to trigger a run

Four ways to say what Outrider should implement. The harness downstream (guardrails, tests, license scan, PR body) is the same for all of them; only where the “why” comes from differs.

Trigger	Where the intent comes from	CLI	Action input
Alerts	The ranker picks from arXiv against your Research Interest on the workflow’s cron	none (scheduled)	none; `interest-id` scopes the pool
Search	You supply a method-family query; the engine search returns the top arXiv hit	`--search-method "riemannian preconditioning LoRA"`	`search-method`
Pin	You name an exact arXiv id	`--pin-arxiv 2410.20305v2`	`pin-arxiv`
Brief	You write the design brief yourself: an issue body, a spec, a notebook. No arXiv anchor	`--brief "add exp backoff to the HTTP client"` or `--brief @design.md`	`mode: brief` + `lead-content`

# paper-anchored: exact arXiv id, or a method-family search
remyxai outrider trigger --repo owner/name --pin-arxiv 2410.20305v2
remyxai outrider trigger --repo owner/name --search-method "riemannian preconditioning LoRA optimizer"

# brief-anchored: a design brief you supply, inline or from disk
remyxai outrider trigger --repo owner/name --brief "add exponential backoff to the HTTP client"
remyxai outrider trigger --repo owner/name --brief @design.md

A pin does not have to be in the candidate pool: the action looks the id up in the Remyx catalog, then on arxiv.org, so any published arXiv paper works (skipped_pin_arxiv_unresolvable if neither resolves). An explicit pin or search also bypasses the don’t-re-recommend throttle, so you can re-run a paper that already has an open artifact. The full flag list is in the CLI reference.

Run from a design brief

mode: brief is the paper-less path. The brief you pass as lead-content is the spec: no ranking, no selection pass, no paper preflight, and no refinement chain. The run clones the repo, writes the brief into the agent’s spec bundle, implements it, runs the same post-session gates as a paper run (path policy, integration check, stub density, self-review, canary, secret scan), and opens a draft PR whose body carries the brief under Design brief instead of a paper attribution. GitHub, Hugging Face, and dataset links in the brief are license-scanned (the first five) and the result lands in the PR’s License section. remyxai outrider trigger --brief is shorthand for --mode brief with the brief as the lead content. @path reads the brief from a file. It can’t be combined with --pin-arxiv, --search-method, --lead-content or --lead-content-file; it can be combined with --start-from-ref to build the brief on top of an existing branch, and with --publish branch to review the output before anything opens. If the installed workflow predates the mode and lead-content inputs, the CLI refuses rather than silently running a paper pass; re-provision with remyxai outrider init --repo owner/name --force. Brief mode is the one mode that runs without an interest-id; when one is configured it is read only for repo context.

Status	Meaning
`pr_opened_brief`	A draft PR was opened from the brief
`branch_pushed_no_pr`	`publish: branch`: the branch was pushed, nothing opened
`brief_declined_open_as_issue`	The agent judged the brief too broad for a PR and wrote an Issue-shaped write-up instead. No Issue is opened yet: the branch is left unpushed for you to review the write-up in the run log
`issue_opened_canary_missing` / `branch_pushed_canary_missing`	The per-run canary was missing from the final commit; routed to an Issue (or kept as a branch) for a human to inspect
`skipped_brief_missing_lead_content`	`mode: brief` ran with an empty `lead-content`
`brief_failed`	The run threw (for example a rejected push). Exits red

In the action directly:

- uses: remyxai/outrider@v1
  with:
    mode: brief
    lead-content: ${{ inputs.brief }}
    # pass a Linear issue URL as the brief and set linear-api-key to have its body fetched

How it works

A run has two stages. The Remyx engine ranks a candidate pool server-side, then Outrider checks candidates against a clone of your repo and decides what to open. Ranking. The pool is ranked from three inputs: your interest’s context, your team’s shipping history (extracted from the merge log), and a learned preference model. Candidates that match the direction your team has shipped rank above topically similar ones. Validation and decision. A high relevance score does not mean a candidate is implementable; the top-ranked paper often has no call site in your repo. A selection pass checks each candidate against the codebase (code search and file reads) and picks the most implementable; if none fit, the run skips. Filters that do not call the model run first, so a run that cannot produce a useful result exits before any LLM cost. Each run ends in one of three outcomes: a draft PR, an Issue, or a skip.

The Outrider pipeline: external sources and your repo feed the Remyx engine's ranking; the action fetches the candidate pool, gates it, selects the most implementable candidate, implements within guardrails, validates, and routes to a draft PR, an Issue, or a skip, with the refinement chain promoting PRs and run telemetry feeding back into ranking

Draft PR

The candidate integrates into an existing call site and passes the validators (tests, stub density, reachability). Outrider opens a draft PR with code and tests.

Discussion Issue

The candidate is relevant but not directly implementable (no call site, too many stubs, or unreachable code). Outrider opens an Issue with the attempted diff.

Skip

No candidate cleared the confidence, dedup, or fit gates. No artifact is created; the run records a status.

When chain is true (the default), opening a draft PR isn’t the end of the run. Outrider keeps going in the same run and walks the draft through three phases before it asks for review:

Fidelity

Diffs the draft against the paper’s reference implementation and emits a coverage matrix: what the diff covers, what it defers, and where it deviates from the source. When no public reference exists, it anchors the audit against the arXiv abstract instead; that’s lower precision and the PR body says so.

Convention

Rewrites the PR body to the repo’s canonical PR template, folds Outrider’s own scaffolding into a collapsible Discovery context block, and applies contributor conventions learned from recent merged PRs. Runs ruff auto-fix and force-pushes the result as the bot.

Test

Runs lint plus a focused pytest on the touched files. On a pass it flips the draft to ready-for-review; on failure the PR stays a draft, labelled outrider:test-failed, for you to take over.

The Issue path gets a convention pass too: mode: issue-convention folds an Issue body to the repo’s ISSUE_TEMPLATE shape. Set chain: false to stop after the first draft: Outrider opens the PR exactly as it first wrote it and runs none of the phases above. That’s the cheaper recommend-only mode.

Labels

The chain records its progress as labels on the PR, which is also how a separate-workflow chain is triggered.

Label	Set when
`outrider:draft`	The draft PR opens (the fidelity phase’s trigger)
`outrider:fidelity-done`	The fidelity audit posted its coverage matrix
`outrider:needs-judgment`	The audit flagged at least one item for human review
`outrider:convention-done`	The convention pass rewrote the body
`outrider:test-failed`	Lint or tests failed; the PR stays a draft
`outrider:issue-convention-done`	An Issue’s body was folded to the repo template
`risky-surface`	The diff touched a dependency manifest, CI, hook, container or shell file (see Guardrails)

Run the chain from separate workflows

Instead of the inline chain, you can drive each phase from a pull_request: labeled workflow with pr-number from the event payload. This is how a phase is re-run against an existing PR.

on:
  pull_request:
    types: [labeled]
jobs:
  fidelity:
    if: github.event.label.name == 'outrider:draft'
    runs-on: ubuntu-latest
    permissions: { contents: write, pull-requests: write }
    env:
      REMYX_API_KEY: ${{ secrets.REMYX_API_KEY }}
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}   # or the secret of the provider you route at
    steps:
      - uses: remyxai/outrider@v1
        with:
          interest-id: ${{ vars.REMYX_INTEREST_ID }}
          mode: fidelity                      # convention / test take the same shape
          pr-number: ${{ github.event.pull_request.number }}

Run outcomes

Every run ends in a status in the Action log and the status output. Statuses marked red make the workflow step exit non-zero; everything else, including Issues and skips, is a legitimate green outcome.

Status	Meaning
`pr_opened`	PR opened ready for review (tests passed and `draft-mode` is not `always`)
`pr_opened_draft`	PR opened as a draft
`issue_opened`	The agent elected Issue mode (wrote a write-up instead of code)
`issue_opened_preflight`	The pre-flight pass routed to an Issue before implementation
`issue_opened_no_integration`	The diff adds code that nothing invokes
`issue_opened_stub_density`	The new module is at least 50% stubs
`issue_opened_no_test_integration`	New tests don’t import from any pre-existing module
`issue_opened_self_review`	The self-review judged the new code an orphan; the Issue preserves the diff
`issue_opened_substitution`	A replacement or extension candidate that needs dependency changes the guardrails block, or has no call site to anchor on
`issue_opened_high_risk`	The diff-risk gate routed to a human-review Issue; the diff is preserved in the body
`issue_opened_canary_missing`	The canary trailer was missing from the final commit; the branch is kept for inspection
`skipped_low_confidence`	Best candidate below `min-confidence`
`skipped_open_artifact`	An open Remyx PR or Issue from a prior run still exists (`rate-limit-days`)
`skipped_by_selection_verification`	The selection pass checked every candidate against the repo and rejected all; the reasoning renders in the step summary
`skipped_pr_exists` / `skipped_issue_exists`	Every candidate already has an open PR, or a prior Issue (open or closed) referencing its arXiv id
`skipped_external_issue_exists`	The selection pass surfaced an out-of-pool candidate the team already has in an Issue
`skipped_arxiv_already_landed`	The pinned paper has already been merged on the target
`skipped_pin_arxiv_unresolvable`	`pin-arxiv` resolved neither in the Remyx catalog nor on arxiv.org
`skipped_no_method_match`	`search-method` returned no usable hit
`skipped_issues_disabled`	The Issue route was needed but Issues are disabled (the default on forks); enable them with `gh repo edit <repo> --enable-issues`
`skipped_fidelity_fabrication` / `skipped_fidelity_fabrication_after_patch`	The pre-PR fidelity gate (`fidelity-policy: block`) found the implementation did not match the reference, before or after its one patch attempt
`skipped_test_failure`	Tests failed and `draft-mode` is `never`
`rejected_path_violations`	The agent touched a blocked path; nothing was pushed
`aborted_secret_in_payload`	The outbound secret scanner matched a credential in the draft payload; nothing was opened. Red
`claude_failed`	The coding-agent CLI exited non-zero. Red
`error`	Unhandled exception. Red

Brief mode, branch mode, smoke, weekly summary

Status	Meaning
`pr_opened_brief` / `brief_declined_open_as_issue` / `skipped_brief_missing_lead_content`	See Run from a design brief
`brief_failed`	A brief run threw. Red
`branch_pushed_no_pr`	`publish: branch`: the branch was pushed and nothing was opened
`branch_pushed_canary_missing`	Branch mode, with the canary missing; review before promoting
`lead_captured_no_issue`	Branch mode would have filed an Issue; the content is in the step summary instead
`smoke_ok` / `smoke_failed`	Whether the configured agent, provider and model reached the vendor (`mode: smoke`)
`weekly_summary_posted` / `weekly_summary_skipped_no_discussion_id`	The digest was posted, or ran with no `weekly-discussion-id`
`weekly_summary_failed`	Nothing was posted. Red

Chain phases

These appear in the chain_*_status outputs of an inline run, or as the run status when a phase runs standalone. The pre-PR gate’s verdict (pre_pr_fidelity_clean / pre_pr_fidelity_advisory / pre_pr_fidelity_needs_judgment / pre_pr_fidelity_skipped_* / pre_pr_fidelity_failed_*) is recorded in the run summary and telemetry rather than as an output; a blocking verdict surfaces as skipped_fidelity_fabrication* above.

Phase	Status	Meaning
Fidelity	`fidelity_audited`, `fidelity_audited_needs_judgment`, `fidelity_audited_paper_anchored`, `fidelity_audited_advisory`	Coverage matrix posted (reference-anchored, or abstract-anchored when no reference exists)
	`fidelity_skipped_no_reference` / `fidelity_skipped_not_bot` / `fidelity_skipped_no_pr` / `fidelity_skipped_reference_mismatch`	Nothing to audit against, or the PR isn’t a `remyx-ai[bot]` draft
	`fidelity_failed_clone` / `fidelity_failed_claude`	Red
Convention	`convention_aligned`	Body rewritten and non-algorithmic alignment patches applied
	`convention_skipped_no_corpus` / `convention_skipped_no_pr` / `convention_skipped_not_bot`	No merged-PR corpus to learn from, or nothing to act on
	`convention_failed_extraction` / `convention_failed_misalignment` / `convention_failed_patch` / `convention_failed_push`	Red
Test	`test_passed`	Lint and tests passed; the draft was moved to ready for review
	`test_failed`	Lint or tests failed; `outrider:test-failed` applied, the PR stays a draft
	`test_skipped_no_pr` / `test_skipped_not_bot`	Nothing to test
	`test_failed_setup`	The test environment could not be set up. Red
Issue convention	`issue_convention_aligned` / `issue_convention_aligned_no_fitting_template` / `issue_convention_skipped_no_templates`	The Issue body was folded to the best template, or folded with scaffolding collapsed when none fit
	`issue_convention_skipped_no_issue` / `issue_convention_skipped_not_bot`	Nothing to act on
	`issue_convention_failed_claude` / `issue_convention_failed_patch`	The model call or the body PATCH failed (`_claude` is red)

The same tables, kept in step with the action, are in the action repo’s docs/configuration.md.

Anatomy of an Outrider PR

As first opened, a PR body is built in a fixed order so you know where to look:

Tests and self-review: what the integration covers, what it left out, and the self-review’s verdict on reachability.
License & code availability: the paper’s reference code and any repos, models or datasets the implementation drew on, with their SPDX ids and a flag when one is copyleft, non-commercial, or missing.
An italic Implements [paper] line linking the arXiv id. A brief-mode PR says it was drafted from a design brief instead, lists the Issues the brief referenced, and carries the brief itself in a collapsed Design brief block.
Discovery context, a collapsed <details> block with Outrider’s scaffolding: the research interest, which agent implemented it, the selection reasoning, and the suggested experiment. Absent on a brief-mode PR, since there was no discovery.
A footer naming the Remyx orchestrator that opened it.
Review before landing, appended only when the diff touched a risky surface; lists the files.

The refinement chain then edits the body in place: the fidelity phase appends a Coverage matrix (covers / defers / deviates against the reference, with a note when the audit was anchored on the abstract only), and the convention phase rewrites the body to your repo’s PR template and folds the scaffolding into the Discovery context block. The body’s last line is a Co-Authored-By: remyx-ai[bot] trailer, kept last through every rewrite, so attribution survives a squash-merge. Relevance scores and confidence lines are not in the body; they live in the run telemetry and the agent report.

Reviewing it

Treat it like a first-pass proposal from a teammate:

Read the self-review and the coverage matrix in the PR body: what the integration covers, what it deferred, and where it deviates from the source.
Run the diff and tests locally; the action runs pytest plus an integration check, but your full suite is the real bar.
Decide: merge, push follow-ups, or close. Your call feeds the agent’s Direction either way, and the Inbox card clears itself when GitHub records the merge or close.

Merged and closed PRs feed back into the agent’s Direction; every decision re-weights what it proposes next. To measure a PR’s effect before deciding, mention @remyx-ai validate on it (Validate).

Next steps

Run Outrider on a repository · Use the CLI · Read the GitHub Action configuration

GET STARTED

WORKFLOWS

HOW IT WORKS

CONFIGURE

REFERENCE

Outrider run modes

Automatic selection

Pinned change

Prepared example

Outcomes

Exact inputs

Ways to trigger a run

Run from a design brief

How it works

Draft PR

Discussion Issue

Skip

Refinement-pass chain

Labels

Run the chain from separate workflows

Run outcomes

Brief mode, branch mode, smoke, weekly summary

Chain phases

Anatomy of an Outrider PR

Reviewing it

Next steps

​Automatic selection

​Pinned change

​Prepared example

​Outcomes

​Exact inputs

​Ways to trigger a run

​Run from a design brief

​How it works

Draft PR

Discussion Issue

Skip

​Refinement-pass chain

​Labels

​Run the chain from separate workflows

​Run outcomes

​Recommend mode

​Brief mode, branch mode, smoke, weekly summary

​Chain phases

​Anatomy of an Outrider PR

​Reviewing it

​Next steps

Automatic selection

Pinned change

Prepared example

Outcomes

Exact inputs

Ways to trigger a run

Run from a design brief

How it works

Refinement-pass chain

Labels

Run the chain from separate workflows

Run outcomes

Recommend mode

Brief mode, branch mode, smoke, weekly summary

Chain phases

Anatomy of an Outrider PR

Reviewing it

Next steps