# AGENTS.md

Gaffer stores and analyzes test results. This file tells a coding agent how to use it. Humans want [gaffer.sh/docs/](https://gaffer.sh/docs/).

## What Gaffer gives an agent

Test history that survives across sessions. Flip rates that separate a flaky test from a real regression. Failure clusters that turn 15 red tests into the 2 bugs actually causing them. Coverage trends per file.

## Three ways in

### 1. CLI

No account needed for local analysis.

```bash
curl -fsSL https://app.gaffer.sh/install.sh | sh
gaffer test -- <your test command>
gaffer query flaky
gaffer query failures "connection refused"
```

`gaffer test` is a drop-in wrapper. The exit code matches the wrapped command and child stdout passes through, so it is safe to substitute anywhere a raw test command appears. Use `--format=json` for a single JSON object on stdout.

For the edit-test loop, one command scopes the run to what changed:

```bash
gaffer test --affected --files path/to/changed-file.ts
```

**Cloud sync needs a credential, but not always a stored one.** On GitHub Actions with `permissions: id-token: write`, `gaffer test`/`gaffer upload` exchange the runner's OIDC token for a project token automatically: no secret to add to CI. Elsewhere, run `gaffer login` once to authenticate via device code; it writes the credential to global config so every later `gaffer test` picks it up. Full flows: [auth.md](https://gaffer.sh/auth.md).

Reference: [gaffer.sh/docs/cli/](https://gaffer.sh/docs/cli/)

### 2. Agent Skill

```bash
npx skills add gaffer-sh/agent-skills
```

Ships the decision rules, not just the commands: when to ignore a flaky failure, how to read the affected-tests signals object, and a dictionary of recurring error patterns. Source: [github.com/gaffer-sh/agent-skills](https://github.com/gaffer-sh/agent-skills)

### 3. MCP server

```bash
claude mcp add gaffer -e GAFFER_API_KEY=gaf_... -- npx -y @gaffer-sh/mcp
```

Code mode: three tools (`execute_code`, `search_tools`, `list_projects`) over a namespace of 17 test-analytics functions. Registry entry: `sh.gaffer/mcp`. Setup: [gaffer.sh/docs/mcp/](https://gaffer.sh/docs/mcp/)

## Rules an agent should follow

**A flaky test is not a bug to fix.** If `gaffer query flaky` reports a flip rate for a failing test, tell the user the rate and move on unless they ask you to investigate.

**Fix the cluster, not the test names.** When failures share an error pattern, the pattern is the root cause. Fixing tests one at a time repeats the same work.

**An empty affected-tests result is ambiguous.** `affected[] == []` means "safe to skip" only when `signals.unavailable == []` too. Otherwise you are in degraded mode: widen scope to the package containing the change.

**Never block on Gaffer.** If install or parse fails, run the raw test command immediately.

## Machine-readable surfaces

| URL | What it is |
|---|---|
| `https://gaffer.sh/llms.txt` | Index of Gaffer for LLMs |
| `https://gaffer.sh/llms-full.txt` | Full documentation, single file |
| `https://gaffer.sh/openapi/v1.yaml` | REST API, OpenAPI 3.1 |
| `https://gaffer.sh/.well-known/api-catalog` | RFC 9727 linkset |
| `https://gaffer.sh/.well-known/mcp/server-card.json` | MCP server card |
| `https://gaffer.sh/.well-known/ai-catalog.json` | ARD agent capability catalog |
| `https://gaffer.sh/auth.md` | How an agent authenticates to the Gaffer API |

Any page on gaffer.sh returns markdown for `Accept: text/markdown`, or append `.md` to the path.

Every page also registers four read-only [WebMCP](https://webmachinelearning.github.io/webmcp/) tools on `document.modelContext` for browser agents: `gaffer.search_docs`, `gaffer.get_pricing`, `gaffer.install_mcp`, `gaffer.signup_url`.

## Source

| Repo | What it is |
|---|---|
| [gaffer-sh/gaffer](https://github.com/gaffer-sh/gaffer) | CLI |
| [gaffer-sh/mcp](https://github.com/gaffer-sh/mcp) | MCP server |
| [gaffer-sh/agent-skills](https://github.com/gaffer-sh/agent-skills) | Agent skills |
| [gaffer-sh/gaffer-uploader](https://github.com/gaffer-sh/gaffer-uploader) | GitHub Action |