Using Selective with coding agents

Coding agents write more tests than people do, and they wait on CI the same way. Selective is built so an agent can do the setup and consume the results without a human in the loop.

Let the agent do the setup

Paste this into your coding agent in a checkout of the repository:

Set up Selective in this repository, completely, following https://selective.ci/llms.txt
(the "Agent setup, in order" section) or https://selective.ci/docs/setup-checklist/.

1. Find every test command the CI config runs; each is one Selective suite. Tell me the
   list so I can create a suite and API key for each.
2. Add the gem (selective-ruby-rspec or selective-ruby-minitest) and the CI platform to
   Gemfile.lock.
3. Swap each test command for `bundle exec selective rspec` / `bundle exec selective minitest`,
   reading the key from a CI secret named SELECTIVE_API_KEY (one secret per suite if there
   are several). Do not commit or print any key.
4. Add the daily map recording job and the warm-up step for this CI provider, from the
   provider's page in the docs.
5. Open a pull request. Tell me which CI files changed and which steps only I can do
   (secrets, the GitHub App, suite modes).
6. After CI runs, check the runner's "Test selection:" line in the output, and stream the
   results with `selective tail` (https://selective.ci/docs/cli).

Creating suites, adding the secrets, installing the GitHub App and setting each suite’s mode are yours; the checklist lists them.

Let the agent read results

Give the agent a token through the environment, never on the command line:

1. Create a token on the API tokens page.
2. Export it as SELECTIVE_TOKEN in the agent’s environment.

Then the agent can run, after pushing a commit:

selective tail --format ndjson

and read one JSON object per line: build_start, then test_pass and test_fail events as tests finish, then a summary. The exit code says how it ended: 0 green, 1 real failures, 2 only flakes, 3 no build yet, 4 auth or network trouble.

Because failures stream as they happen and the tests most likely to fail run first, an agent can act on the first test_fail instead of waiting for the run to finish: fix and push again, or decide the change is wrong and abandon it.

Investigating a flake

On the flakes dashboard, each flaking test has a copy prompt action that produces a description of the flake, its recent occurrences and the tests that ran before each one. Hand that to an agent and ask it to reproduce and fix.

llms.txt

selective.ci/llms.txt is the whole setup and usage guide in one plain-text file, written for agents. Point yours at it.