# Skill: Set up Haystack on a repository

You are a coding agent. Use this skill when your user asks to add Haystack — AI code review, PR triage/QA, and a self-driving merge queue — to a GitHub repository.

## Prerequisites (check before starting)

- The repository has a GitHub remote (`git remote -v` → `owner/name`)
- Node.js 18+ is available
- Your user has admin access to the repository (required to install a GitHub App)

## Steps

### 1. Install the CLI

```bash
npm install -g @haystackeditor/cli
```

If global installs aren't allowed in your environment, every command below also works without installing:

```bash
npx -y @haystackeditor/cli@latest <command>
```

**Always pin `@latest` with npx** — a bare `npx @haystackeditor/cli` reuses whatever version is in the npx cache, which can be months old and missing the flags documented here. If a documented flag is rejected, check `haystack --version` against `npm view @haystackeditor/cli version` first.

The canonical package is `@haystackeditor/cli` (bin name: `haystack`). The unscoped `haystack` package on npm is an unrelated string-matching library — do not install it.

### 2. Authenticate

```bash
haystack login
```

This starts a GitHub device flow: it prints a one-time code and the URL `https://github.com/login/device`. Relay the code to your user and wait for them to complete authorization in their browser. The command blocks until login finishes.

### 3. Install the GitHub App

Haystack analyzes PRs via the GitHub App. Send your user to:

```
https://github.com/apps/haystack-code-reviewer-pr-hook/installations/new
```

They should install it on the target repository (or the whole org). `haystack setup` verifies this and will tell you if the App is missing.

### 4. Run setup

Non-interactive (recommended for agents):

```bash
haystack setup --repo owner/name --yes
```

Or full agent mode — NDJSON events on stdout, answers on stdin, no TTY prompts:

```bash
haystack setup --json --repo owner/name
```

Useful flags: `--auto-merge` / `--no-auto-merge` (enable the merge queue without being asked), `--skip-entire` (skip session-tracking git hooks), `--answers <file>` (pre-supplied answers as JSON).

Setup scans the repo for conventions, CI signals, and review policies, then writes `.haystack.json`, `.haystack/pr-rules.yml`, and `review-policy.md`.

### 5. Commit the generated config

```bash
git add .haystack.json .haystack/ review-policy.md
git commit -m "Add Haystack configuration"
git push
```

### 6. Verify

Open any pull request on the repo (or use an existing one) and run:

```bash
haystack triage owner/name#<pr-number>
```

You should see a rating and findings once analysis completes (typically a few minutes after the PR is opened or updated).

## Optional: MCP server

The CLI includes an MCP server exposing Haystack's read surface (`triage_pr`, `pr_state`, `schema`) to any MCP client:

```bash
# Claude Code
claude mcp add haystack -- haystack mcp
```

Or in a JSON MCP config (Cursor, Windsurf, etc.):

```json
{
  "mcpServers": {
    "haystack": { "command": "haystack", "args": ["mcp"] }
  }
}
```

## Optional: verification sandbox (risk-based QA)

To have Haystack build and exercise the app end-to-end on every PR, install the setup skills and run them in your coding CLI:

```bash
npx -y @haystackeditor/cli@latest skills install
```

Then run `/setup-haystack` (configures build, dev server, flows, auth for the sandbox) and `/prepare-haystack` (adds test IDs). See [Verification Flow](/docs/verification-flow.md).

## If you cannot complete a human step

Two steps need a human: the device-flow login (step 2) and the GitHub App install (step 3). If your environment can't wait for them, stop and send your user this message, then resume at step 4 once they confirm:

> To finish Haystack setup I need two things from you:
> 1. Run `haystack login` in a terminal (or give me the go-ahead to run it and relay you the one-time code for github.com/login/device).
> 2. Install the Haystack GitHub App on the repo (needs admin): https://github.com/apps/haystack-code-reviewer-pr-hook/installations/new
>
> Once both are done, I'll run `haystack setup --repo owner/name --yes` and commit the config.

## Troubleshooting

- A documented flag is rejected (e.g. `unknown option '--repo'`) → you're running a stale cached version; re-run via `npx -y @haystackeditor/cli@latest`.
- `haystack setup` reports the GitHub App is not installed → step 3; requires repo admin.
- `haystack triage` loops "in progress" on a private repo → your user's GitHub account must have access to the repo.
- All docs are agent-readable: append `.md` to any docs URL, or fetch [/llms-full.txt](/llms-full.txt).