AI Diff Reviewer — Setup Wizard (sub-skill)

Companion to the `ai-diff-reviewer` skill. Where the parent
runs the review and `generate-extension`
tailors the prompt, this sub-skill bootstraps the GitHub Action
itself — walks the developer through the ~6 key decisions and writes
a working .github/workflows/pr-review.yml tailored to those choices.

Also doubles as the reference manual for every action.yml input:
if a developer asks any coding agent "what does strictness do?" or
"how do I run only when a label is added?", the agent can read
`reference.md` in this directory and answer without
opening the source.

---

When it fires

Explicit triggers (recommended):

• "Set up AI Diff Reviewer for this repo"
• "Configure the reviewer action"
• "Install the AI Diff Reviewer GitHub Action"
• "Help me create the pr-review workflow"
• "How do I add AI Diff Reviewer to this project?"

The parent `ai-diff-reviewer` skill may also route here
automatically when a review-flow request activates on a repo that
clearly has no .github/workflows/pr-review.yml (opt-in — future
enhancement; not the default today).

---

Step 0 — Trust boundary

This skill writes exactly two categories of files, both with
explicit developer consent:

• .github/workflows/pr-review.yml — the tailored workflow after
  all six questions are answered. If a file already exists at that
  path, the skill ASKS before overwriting (offers to write to
  pr-review-new.yml alongside for review).
• .review/extension.md — only if the developer says yes to
  the optional Step 5 handoff, which invokes the
  `generate-extension` sub-skill.

It does not:

• Commit anything, push anything, or open a PR — the developer stages
  and commits themselves.
• Touch GitHub Secrets — they're set once by the developer in the
  repo's Settings UI (link surfaced in Step 4).
• Modify existing unrelated workflows in .github/workflows/.
• Call the LLM provider directly or send data off the machine.

---

Step 1 — Discovery (light — target ≤ 6 tool calls)

Gather just enough to pick sensible defaults; don't do a full
generate-extension-style Discovery.

1a. Repo identity

# Slug (owner/repo)
git remote get-url origin | sed -E 's|.*[:/](.+/.+)\.git$|\1|'

# Public or private? (gh required; skip cleanly if absent)
gh repo view --json isPrivate,visibility 2>/dev/null

1b. Existing workflows

ls .github/workflows/*.yml 2>/dev/null
test -f .github/workflows/pr-review.yml && echo "EXISTS"

If pr-review.yml (or a similarly-named workflow) already exists,
tell the developer and offer three paths:

1. Overwrite — replace the existing file (require them to confirm
   yes overwrite, not just yes).
2. Side-by-side — write to .github/workflows/pr-review-new.yml
   so they can diff and merge manually.
3. Cancel — abort the setup entirely.

1c. Stack detection (defaults hint)

# Presence of any of these tells you the primary language / ecosystem.
ls package.json pnpm-lock.yaml yarn.lock 2>/dev/null   # Node
ls pyproject.toml requirements*.txt Pipfile 2>/dev/null # Python
ls go.mod 2>/dev/null                                   # Go
ls Cargo.toml 2>/dev/null                               # Rust
ls Gemfile 2>/dev/null                                  # Ruby
ls pom.xml build.gradle 2>/dev/null                     # Java/Kotlin

The stack shapes only one suggestion downstream: whether the CLI
providers make sense (claude-code / cursor / codex all need
Node 20 to install, which is fine on ubuntu-latest regardless of
your project's language, but the workflow's timeout-minutes may
want to be higher for larger diffs).

1d. Default branch

gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo "main"

Used to fill on.pull_request.branches: [<default>] in the composed
workflow.

---

Step 2 — The six questions

Ask them one at a time, showing the default marked as
(recommended) in the response so the developer can just say "go
with defaults" and get the safest workflow in ~30 seconds. Use the
Discovery data to pre-fill anything you can (e.g. default_branch,
visibility).

Q1 — Runner and backend

Two short questions. The runner is who drives the review loop
(provider input); the backend is where the model lives
(api-base input, empty for the runner's own vendor).

Q1a — Which runner should run the review?

• anthropic (recommended for first setup) — in-process, zero
  install, bounded loop, prompt caching. Cheapest predictable choice.
• openai — the same in-process loop for OpenAI-compatible
  backends (OpenAI, Azure Foundry, xAI, Z.ai via api-base).
• claude-code — Claude Code CLI headless. Deeper agentic
  review; accepts a subscription OAuth token (sk-ant-oat…) to bill a
  Claude Pro/Max plan; also the recommended runner for Z.ai GLM.
• codex — OpenAI Codex CLI headless. Best if the team already
  has OpenAI or Azure Foundry billing (api-base for Azure).
• grok — xAI Grok CLI headless (web search / subagents off,
  native turn cap). Best if the team is on xAI credits.
• cursor — Cursor Agent CLI headless; model: auto is
  unlimited on Cursor Pro. No api-base lane.

Q1b — Where does your model live? (skip for cursor; skip when
the answer is "the runner's own vendor")

Anthropic · OpenAI · Azure Foundry · xAI · Z.ai · self-hosted gateway

Resolve the pair into the three values the workflow needs:

Runner	Backend	api-base	Secret name	Suggested model
anthropic	Anthropic	(empty)	ANTHROPIC_API_KEY	balanced
anthropic	Z.ai	https://api.z.ai/api/anthropic	ZAI_CODING_API_KEY	balanced
anthropic	xAI	https://api.x.ai	XAI_API_KEY	balanced
openai	OpenAI	(empty)	OPENAI_API_KEY	balanced
openai	Azure Foundry	https://<resource>.services.ai.azure.com/openai/v1 (or …openai.azure.com/openai/v1)	AZURE_OPENAI_API_KEY	the deployment name
openai	xAI	https://api.x.ai/v1	XAI_API_KEY	balanced
openai	Z.ai	https://api.z.ai/api/coding/paas/v4	ZAI_CODING_API_KEY	balanced
claude-code	Anthropic (API key)	(empty)	ANTHROPIC_API_KEY	balanced
claude-code	Anthropic (subscription)	(empty)	CLAUDE_CODE_OAUTH_TOKEN (claude setup-token)	balanced
claude-code	Z.ai (recommended for GLM)	https://api.z.ai/api/anthropic	ZAI_CODING_API_KEY	balanced
codex	OpenAI	(empty)	OPENAI_API_KEY	balanced
codex	Azure Foundry	as for openai + Azure	AZURE_OPENAI_API_KEY	the deployment name
grok	xAI	(empty)	XAI_API_KEY	balanced
cursor	Cursor	(none)	CURSOR_API_KEY	auto
any in-process runner	self-hosted gateway	https://<your-gateway>/… (custom host — the run warns where the key goes)	your gateway's key	the gateway's model id

Recommendation shortcuts when the developer asks "which one?":

• Cheapest, predictable, zero install → anthropic (or openai).
• Deepest review (agentic file exploration) → claude-code
  (codex / grok if that vendor is already paid for).
• Flat-rate billing → cursor (Pro), claude-code + Z.ai Coding
  Plan, or claude-code + a Claude subscription token.
• Azure-only shops → codex + Azure Foundry (agentic) or
  openai + Azure Foundry (in-process). Note: Codex on xAI is not
  usable today (Codex ≥ 0.154 sends a tool type xAI rejects) — use
  grok or openai for xAI.

Whatever the pair, suggest model: balanced (one word, resolved per
runner × backend from the dated matrix in docs/PROVIDERS.md § "Cost-efficient defaults matrix"; economy for smoke passes, deep for high-risk
PRs). Azure deployments and custom gateways have no tier rows — pass the
concrete name.

Record: PROVIDER, API_BASE (may be empty), SECRET_NAME, MODEL.

Q2 — Strictness

When should the GitHub check fail?

• lenient (recommended for weeks 1–2) — The check never
  fails; every review posts, no PR is ever blocked. Use this to
  calibrate the prompt and the extension against your codebase
  without breaking anyone's merge flow.
• block-on-critical (recommended for steady-state) —
  Fails only if the reviewer marks any comment as critical
  (security, data loss, breaking API). Warnings and info-level
  comments still post but don't gate merges.
• block-on-warning — Fails on warning OR critical.
  Aggressive; only recommended when the extension has been tuned
  to keep false positives near zero.
• block-on-any — Fails on ANY inline comment, including
  info. Zero-tolerance mode for security-critical or regulated
  stacks.

Record: STRICTNESS.

Q3 — Trigger mode

When should the reviewer run?

• on every push to the PR (recommended for most teams) — Uses
  types: [opened, synchronize]. Reviews the diff on the first
  open and again every time new commits are pushed. Predictable
  feedback loop for the author.
• only when a ready label is applied — Uses
  trigger-mode: label-once + label-gate: ready. Keeps WIP PRs
  quiet; costs run only when the author explicitly signals
  readiness. Toggle the label off/on to re-run. Best for cost
  discipline in large repos.
• only on labeled events — Uses trigger-mode: label-added-only and subscribes to types: [labeled]. Even
  more conservative; the workflow doesn't run on synchronize
  at all, so new commits after the label was applied don't
  trigger new reviews (only re-labeling does).

Record: TRIGGER, plus LABEL_GATE (empty or ready) and the
workflow event types.

Q4 — External contributors

Who should be allowed to trigger the review?
(Applies mostly to public open-source repos.)

• OWNER,MEMBER,COLLABORATOR (recommended for public repos) —
  Only writes-tier authors trigger the review. Blocks external
  contributors from opening PRs to burn your API budget.
• OWNER,MEMBER,COLLABORATOR,CONTRIBUTOR — Also allows
  returning contributors (people whose PRs you've merged before).
  Good middle ground once you have a stable contributor pool.
• empty string '' — Review every PR from anyone.
  Optional on private repos; risky on public ones.

On private / internal repos, keep the default
OWNER,MEMBER,COLLABORATOR — the action also checks collaborator
permission when GitHub's webhook under-reports membership (common with
team-granted org access). Only choose '' if you want the gate fully
disabled.

Record: AUTHOR_ASSOC.

Q5 — PR description mode

Should the reviewer also check that PR descriptions are meaningful?

• off (recommended if you don't have PR-body standards yet) —
  Ignore the description entirely.
• warn — Flag "missing/vague description" in the review
  summary (doesn't affect the strictness gate).
• block — Force the check to fail if the description is
  missing/vague, regardless of strictness. Cheap way to enforce
  PR hygiene.
• autocomplete — The reviewer AI writes a first-draft body
  for you. Guarded by a marker so it never overwrites your edits.
  Best UX for solo maintainers.

Record: PR_DESC_MODE. If the developer picks anything other than
off, ask a follow-up: "Minimum character count?" (default 50).

Q6 — Complexity labels

Should the reviewer apply complexity labels (complexity:low /
complexity:medium / complexity:high) to PRs?

• no (recommended for first setup) — Skip this feature until
  you have a use case for it.
• yes — The reviewer assesses cognitive load / files touched /
  security surface / coverage delta and applies a label. Useful for
  triage boards, code-owner routing, or PR-size KPIs. Adds a small
  amount of latency + one more label the team has to reason about.

Record: COMPLEXITY_LABELS.

---

Step 3 — Compose and write the workflow

Assemble the YAML from the recorded answers. Template below (variables
in <ANGLE_BRACKETS> come from Step 2's answers; the header comment is
generated so the developer knows which options this file reflects).

# AI Diff Reviewer — generated by the setup skill.
# Source: https://github.com/DailybotHQ/ai-diff-reviewer
#
# What's configured here:
#   - Runner: <PROVIDER>  (backend: <BACKEND_HUMAN or "vendor default">)
#   - Strictness: <STRICTNESS>
#   - Trigger: <TRIGGER_HUMAN>  (<TRIGGER>)
#   - External contributors: <AUTHOR_ASSOC or "unrestricted">
#   - PR description mode: <PR_DESC_MODE>
#   - Complexity labels: <yes|no>
#
# Regenerate: run the ai-diff-reviewer-setup skill again.

name: PR review
on:
  pull_request:
    branches: [<DEFAULT_BRANCH>]
    types: [<EVENT_TYPES>]     # e.g. [opened, synchronize]

concurrency:
  group: pr-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # required — the action runs `git diff origin/<base>...HEAD`
          <agent-runners only: persist-credentials: false   # the CLI must never find the GITHUB_TOKEN in .git/config>

      - uses: DailybotHQ/ai-diff-reviewer@v3
        <agent-runners only: if: github.event.pull_request.head.repo.full_name == github.repository   # trusted (non-fork) PRs>
        with:
          provider: <PROVIDER>
          api-key: ${{ secrets.<SECRET_NAME> }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          <optional: api-base: <API_BASE>>          # only when the backend is not the runner's vendor
          <optional: model: <MODEL>>                # `balanced` recommended; deployment name on Azure
          strictness: <STRICTNESS>

          # Only include the lines below when they differ from action defaults.
          <optional: trigger-mode: <TRIGGER>>
          <optional: label-gate: <LABEL_GATE>>
          <optional: author-association: '<AUTHOR_ASSOC>'>
          <optional: pr-description-mode: <PR_DESC_MODE>>
          <optional: pr-description-min-length: <MIN_LEN>>
          <optional: complexity-labels-enabled: 'true'>

Rules for the composition:

1. Omit every input that matches its action default. The result
   should read like a hand-written minimal workflow, not a giant
   config dump. Explicit inputs only for the choices that differ.
2. Never emit a placeholder secret value. Use
   ${{ secrets.<SECRET_NAME> }} — the developer wires it in Step 4.
3. Header comment reflects reality. If the trigger is
   label-added-only, the comment must say so and the event types
   must match — don't ship a mismatch.
4. applied-label and collapse-previous are not asked (they
   default to sensible values); the composed workflow inherits both
   defaults silently.
5. prompt-extension-file is not asked in the wizard — it's set
   later, either by the developer or by Step 5's handoff to
   generate-extension.
6. Agent-runner hardening lines are not optional for claude-code,
   cursor, codex and grok: emit persist-credentials: false on the
   checkout and the non-fork if: on the action step (the CLI runs with
   broad local access — docs/SECURITY.md § "Agent-runner providers").
   Omit both for anthropic / openai.
7. api-base is emitted only when set, and model only when the
   developer accepted a tier alias or the backend needs a concrete name
   (Azure deployment, custom gateway).

Write the file:

mkdir -p .github/workflows
# Write the composed YAML to .github/workflows/pr-review.yml (or
# pr-review-new.yml if the developer picked "side-by-side" in Step 1b)
# via the harness's file-write tool.

---

Step 4 — Post-setup instructions

After the file is written, tell the developer the exact next steps.
Include the repo-specific URL — makes the friction go away.

Workflow written to `.github/workflows/pr-review.yml`. Next steps:

1. **Add the API secret.**
   Go to: https://github.com/<OWNER>/<REPO>/settings/secrets/actions/new
   Name: `<SECRET_NAME>`
   Value: your key from <BACKEND_CONSOLE_URL>

2. **Commit + test.**
   ```bash
   git checkout -b chore/setup-ai-diff-reviewer
   git add .github/workflows/pr-review.yml
   git commit -m "chore: add AI Diff Reviewer GitHub Action"
   git push -u origin chore/setup-ai-diff-reviewer

Open a draft PR. The reviewer will run on the first push, post its
findings, and (given your <STRICTNESS> choice) either gate the
check or just comment.

3. Only if you picked label-gate: ready (Q3, second option):
   also create the label on the repo before merging the workflow.

   gh label create ready --color 0e8a16 --description "Signals PR is ready for AI review"

4. Defaults you already have (no extra config needed).
   Iteration-Aware Review runs on every CI review with
   convergence-policy: first-pass-exhaustive — exhaustive first
   pass, then dedup on later rounds so the same warnings don't
   trickle forever. To force a full un-deduped pass once, label
   the PR full-review-please (the shipped
   iteration-escape-label). Optional emergency bypass for
   hotfixes: add skip-review-label: skip-ai-review to the
   workflow and protect that label with a ruleset — see
   examples/skip-review-label.yml and
   docs/ITERATION_AWARENESS.md / docs/TRIGGER_MODES.md in the
   action repo.

Provider-console URLs to substitute in the instructions:

| Backend (secret name) | Console URL for the key |
|---|---|
| Anthropic (`ANTHROPIC_API_KEY`) | https://console.anthropic.com/settings/keys |
| Anthropic subscription (`CLAUDE_CODE_OAUTH_TOKEN`) | run `claude setup-token` locally and paste the `sk-ant-oat…` token |
| OpenAI (`OPENAI_API_KEY`) | https://platform.openai.com/api-keys |
| Azure Foundry (`AZURE_OPENAI_API_KEY`) | Azure portal → your AI Foundry / Azure OpenAI resource → Keys and Endpoint (the endpoint host becomes `api-base`) |
| xAI (`XAI_API_KEY`) | https://console.x.ai → API keys |
| Z.ai (`ZAI_CODING_API_KEY`) | https://z.ai/manage-apikey/apikey-list (Coding Plan key) |
| Cursor (`CURSOR_API_KEY`) | https://cursor.com/dashboard → Settings → API Keys |

When `API_BASE` is set, add one line to step 1 of the instructions: *"The
key is sent only to `<API_BASE host>`; the action refuses malformed
endpoints before any call."*

---

## Step 5 — Optional handoff: bootstrap the extension file

After the workflow is written, ask ONE more question:

> **Want to also tailor the review to this repo?**
>
> The workflow uses the shipped default prompt right now — great for
> general-purpose review, but it doesn't know YOUR conventions
> (money-handling in `<detected-stack>`, banned patterns, etc.).
>
> I can bootstrap a `.review/extension.md` for this repo now
> (~30 seconds of Discovery + a ~100-line file). The workflow will
> auto-detect it if you also add
> `prompt-extension-file: .review/extension.md` to the `with:` block,
> and the local review skill picks it up too.
>
> - **yes** — invoke `generate-extension` now.
> - **no** — skip; the shipped default is fine. Run
>   `generate-extension` any time later.

Handle:

- **yes** → invoke [`generate-extension`](../generate-extension/SKILL.md)
  in extension mode. After it writes `.review/extension.md`, update the
  freshly-composed workflow file to add
  `prompt-extension-file: .review/extension.md` (a two-line
  in-place edit). Announce both files at the end.
- **no** → stop after Step 4. Tell the developer they can bootstrap
  the extension later ("say 'generate a `.review/extension.md`' any
  time — one command, zero re-config").

---

## Reference — all action inputs

The full input table with description, default, and per-scenario
recommendations lives in [`reference.md`](reference.md) in this
directory. Read it directly when the developer asks a specific
question about any input the wizard didn't cover
(`mcp-config-file`, `max-turns`, `agent-extra-args`, etc.).

Any coding agent with this skill installed can answer
*"what does `<input>` do?"* by consulting `reference.md` alone — no
need to open `action.yml`.

---

## Notes

- **The wizard is the happy path; `reference.md` is the escape hatch.**
  If the developer wants to hand-craft a workflow with knobs the
  wizard doesn't ask about (`mcp-config-file`, `max-turns`, model
  pinning, etc.), point them at `reference.md` and let them compose
  themselves.
- **Re-running the wizard is safe.** If a `.github/workflows/pr-review.yml`
  already exists, the skill offers overwrite / side-by-side / cancel.
  Overwriting requires the explicit phrase `yes overwrite`, not just
  `yes`.
- **The composed workflow tracks the moving major tag** (`@v2`) by
  default so consumers pick up patches and minor features
  automatically. To pin, edit the `uses:` line to a specific
  `@vX.Y.Z` — the auto-release workflow keeps the major tag in sync
  on every release.
- **`prompt-extension-file` is deliberately not asked** in the
  wizard — the developer either doesn't have one yet (Step 5 offers
  to generate it) or already knows the path (in which case they can
  hand-edit the workflow after).
- **Bugs, feature requests, or "the wizard didn't ask about X":**
  https://github.com/DailybotHQ/ai-diff-reviewer/issues.