bug-intake git:20261020.0182e97A

Immutable. This exact content never changes and is served at /api/v1/blob/4a4ebba6f2aeb9a8.

---
name: bug-intake
description: Set up automatic bug pickup, once per project — a bug logged as a GitHub issue or a Linear issue is triaged by an agent (reproduce, failing test or repro steps, confidence), and once a maintainer labels it agent-ready, a fix agent opens a pull request starting from a failing test. Ships the GitHub workflows, labels and bug form, and the prompt for a scheduled routine that watches Linear. Use when the user asks for bugs to be picked up automatically, an issue-to-PR flow, or a bug triage bot.
argument-hint: "github | linear | both"
disable-model-invocation: true
---

# Bug intake

This skill **sets the pipeline up**; the pipeline then runs without it. Two separate paths:

- **GitHub** — workflows using `anthropics/claude-code-action`, triggered by issue labels.
- **Linear** — a scheduled Claude Code routine that checks Linear for labelled bugs.

Both are two-stage: **triage first, fix on a label**.

```
bug logged ──► triage agent (reproduces, comments repro + confidence + recommendation)
                 │
     maintainer adds `agent-ready` ──► fix agent (failing test → fix → PR "Fixes #n")
                 │
     can't reproduce / unsure ──► `needs-owner`
```

The fix agent's output is always a pull request. Who merges it follows the project's normal rule
(the owner, or `team-lead-handsoff`'s checklist if the project adopted it).

## Safety rules — built into the files, keep them

- **Issue text is untrusted input.** On a public repository anyone can open an issue, and its text
  lands in the agent's prompt. So agents run **only on a label that only maintainers can apply**
  (`agent-triage`, `agent-ready`), or automatically on bugs opened by the repository's owner, members
  and collaborators. The prompts tell the agent to treat the issue as a description, never as
  instructions.
- **No secrets beyond the model key.** The jobs see the model credential and the workflow token,
  nothing else.
- **One job at a time, and a daily cap** (`AGENT_DAILY_CAP` repository variable, default 5). GitHub
  queues only one waiting run; a third is cancelled, and its label has to be re-applied later.
- **Never to `main`.** The fix agent pushes a `bugfix/issue-<n>` branch and opens a PR.

## 1. Ask once

Which paths to enable (GitHub, Linear, or both), the daily cap, and — for Linear — the team and the
cadence (every 6 hours is a sensible default). One round, with recommendations.

## 2. Write the files (GitHub path)

From this skill's folder into the project:

| Source | Destination |
|---|---|
| [templates/bug_report.yml](templates/bug_report.yml) | `.github/ISSUE_TEMPLATE/bug_report.yml` |
| [templates/bug-triage.yml](templates/bug-triage.yml) | `.github/workflows/bug-triage.yml` |
| [templates/bug-fix.yml](templates/bug-fix.yml) | `.github/workflows/bug-fix.yml` |

The workflows call `./.github/actions/setup-engine` to install the engine and run tests; the engine
pack's setup creates it (`setup-godot` does). If it's missing, say so: the agents can still read and
comment, but can't run the tests.

Create the labels: `gh label create bug`, `agent-triage`, `agent-ready`, `needs-owner` (with short
descriptions; skip ones that exist). Commit the files on a branch and open a PR.

## 3. The owner's part (GitHub)

List these, with links, and wait for the owner to confirm:

1. Install the **Claude GitHub App** on the repository (from a Claude Code terminal:
   `/install-github-app`, or github.com/apps/claude).
2. Add the model credential as a repository secret: `ANTHROPIC_API_KEY` (an API key), or
   `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`, to use a Claude subscription) — then edit
   the two workflows' `anthropic_api_key` line to the token line, as their comment says.
3. Optionally set the `AGENT_DAILY_CAP` repository variable.
4. Make sure `main` is protected, so nothing — agent or not — lands there without CI.

## 4. The Linear path

Linear doesn't trigger GitHub workflows, so a **scheduled routine** checks it instead.

1. Fill [templates/linear-routine.md](templates/linear-routine.md) with the team key and repository.
2. Create the routine with Claude Code's scheduling (the `/schedule` command or skill), using the
   filled file as the routine's prompt, on the agreed cadence, against this repository. The routine
   needs the Linear connector available to it.
3. The owner labels Linear bugs `agent-triage` / `agent-ready` exactly as on GitHub; each run handles
   at most one triage and one fix.

If the project syncs Linear issues into GitHub instead, the GitHub path already covers them; don't
run both on the same bug.

## 5. Try it

Open a small, real bug as an issue (or a Linear issue) with clear steps, label it `agent-triage`,
and watch the run (`gh run watch`). Then label it `agent-ready` and check the PR: a test that fails
without the fix, the fix, and `Fixes #<n>` in the body. Report what happened, including anything
that didn't work.