Issue Triage

This example runs two cooperating agents. issue-triage wakes for every new GitHub issue (and whenever a human re-requests triage with a label): it dedupes, prioritizes, labels, splits mixed reports, and asks for missing context. When an issue is clear enough to implement, it hands off to shepherd — the implementation owner that opens a pull request, carries it through review, and comments back on the issue with the PR link, tests run, and residual risks. Use it when your issue tracker accumulates faster than anyone grooms it, and you want vague reports turned into implementation-ready work — or shipped PRs — without a human dispatcher. GitHub Issues is the base; a Linear variant swaps the source of truth.

How it works

Agent	Triggers	Routing	Writes
`issue-triage`	`github.issue.opened`; `github.issue.labeled` filtered to the `auto-triage` label	`bind` on `github.issue`, `onUnmatched: spawn`	Issue labels, state, and comments (`issues: write`); never code
`shepherd`	none required for this handoff — it is spawned by triage via the `auto.sessions.spawn` tool	—	A feature branch, one PR carried through review, and one closing issue comment (`contents: write`, `pullRequests: write`)

Two mechanics carry the example:

The issue binding. Both triage triggers route bind on the github.issue target with onUnmatched: spawn: the first event on an issue spawns a session already bound to it, and a repeat event on an issue whose triage session is still live delivers into that session instead of spawning a duplicate.
Agent-to-agent handoff. Triage calls the auto.sessions.spawn tool with agent: shepherd and a message carrying the issue number, URL, triage summary, acceptance criteria, and constraints. Shepherd receives the full brief in the spawn message, so this dispatch path needs no duplicate issue trigger.

The auto-triage label is a one-shot request token, not a standing subscription: triage removes it once it has acted, so re-applying the label is how humans request another pass.

Install from the managed template

Issue Triage and Shepherd are separate retained roles in @auto/agents:

.auto/agents/issue-triage.yaml

name: issue-triage
imports:
  - "@auto/agents@latest/issue-triage.yaml"
variables:
  repoFullName: acme/widgets
  githubConnection: github-acme

.auto/agents/shepherd.yaml

name: shepherd
imports:
  - "@auto/agents@latest/shepherd.yaml"
variables:
  repoFullName: acme/widgets
  githubConnection: github-acme

For the Linear substrate, import @auto/agents@latest/issue-triage-linear.yaml. The catalog installer automatically adds this optional Linear reporting overlay to the separately installed Shepherd; add the same overlay to a hand-authored facade:

.auto/agents/shepherd.yaml (Linear overlay)

systemPrompt:
  append: |

    For a Linear issue dispatched by Issue Triage, use chat.send with target
    provider `linear` to post the PR link, tests, final status, and residual risks.
tools:
  linear:
    kind: local
    implementation: chat
    auth:
      kind: connection
      provider: linear
      connection: linear
      optional: true

The handoff arrives through auto.sessions.spawn, so Shepherd needs the Linear chat tool but no duplicate Linear event trigger. Merge to your production branch for GitHub Sync to apply.

The full configuration

.auto/
  agents/issue-triage.yaml
  agents/shepherd.yaml
  assets/triage.png
  assets/patch.png
  fragments/environments/agent-runtime.yaml

.auto/fragments/environments/agent-runtime.yaml

harness: claude-code
environment:
  name: agent-runtime
  image:
    kind: preset
    name: node24
  resources:
    memoryMB: 8192

.auto/agents/issue-triage.yaml

name: issue-triage
model:
  provider: anthropic
  id: claude-opus-4-8
identity:
  displayName: Issue Triage
  username: issue-triage
  avatar:
    asset: .auto/assets/triage.png
  description: Triages labeled issues - sets metadata, posts handoff context, queues Shepherd-ready work, and optionally notes it in Slack.
imports:
  - ../fragments/environments/agent-runtime.yaml
systemPrompt: |
  You are the issue triage agent for acme/widgets. Work from GitHub Issues
  as the source of truth, using issue_read, issue_write, and add_issue_comment
  through the github tool to inspect, update, and comment on issues.

  The `auto-triage` label is a one-shot request token, not a standing
  subscription. Remove it with issue_write once you have acted on the request.

  Triage responsibilities:
  - Identify duplicates; close or link them only when the match is clear,
    preserving important detail on the parent issue.
  - Rank priority from impact, urgency, user signal, and blocked work.
    Explain non-obvious priority changes in a GitHub issue comment.
  - Categorize with the most specific existing labels you can justify. Never
    create GitHub labels — if the expected label does not exist, note that in
    a comment and continue without it.
  - Split broad reports into targeted child issues when one issue mixes
    unrelated tracks; keep the parent as context.
  - Ask for missing reproduction steps, desired behavior, or acceptance
    criteria in a GitHub issue comment. Do not invent requirements.

  When an issue is clear enough to implement:
  - Comment on the issue with concise handoff context for Shepherd.
  - Remove the `auto-triage` label with issue_write.
  - Call auto.sessions.spawn with agent `shepherd` and a message carrying
    the issue number, title, URL, triage summary, acceptance criteria,
    and constraints. Tell Shepherd to open a PR against main with a Review
    Map section and to comment back on the GitHub issue with the PR link,
    tests run, and residual risks.
  - When the chat tool is available, also post a brief note in Slack #dev: a
    top-level message with only the issue link and a one-sentence reason it
    is ready, details threaded. Slack renders mrkdwn links:
    <https://url|text>.

  Slack reporting is optional zero-configuration wiring using the standard
  `slack` connection name and `#dev` channel. When the chat tool is
  unavailable, skip the Slack steps and do not treat that as a failure —
  GitHub comments remain the complete triage record.

  Keep changes small and reversible. Prefer comments that explain what you
  did over silent metadata churn. When posting GitHub comments, append this
  hidden attribution marker with the environment variables expanded:

    <!-- auto:v=1 session_id=$AUTO_SESSION_ID agent=$AUTO_AGENT_NAME -->
initialPrompt: |
  Triage GitHub issue #{{github.issue.number}}: {{github.issue.title}}

  Trigger event: {{type}}
  Issue URL: {{github.issue.htmlUrl}}

  Inspect the issue and related GitHub context with issue_read, then apply
  your triage instructions. Remember the `auto-triage` label is a one-shot
  request token — remove it with issue_write once you have acted.
mounts:
  - kind: git
    repository: acme/widgets
    mountPath: /workspace/repo
    ref: main
    auth:
      kind: githubApp
      capabilities:
        contents: read
        pullRequests: none
        issues: write
        checks: none
        actions: none
workingDirectory: /workspace/repo
tools:
  auto:
    kind: local
    implementation: auto
  github:
    kind: github
    tools:
      - issue_read
      - issue_write
      - add_issue_comment
  chat:
    kind: local
    implementation: chat
    auth:
      kind: connections
      optional: true
      connections:
        - provider: slack
          connection: slack
triggers:
  - name: issue-opened
    event: github.issue.opened
    connection: github-acme
    where:
      $.github.repository.fullName: acme/widgets
      $.github.auto.authored: false
    message: |
      A new issue was opened on acme/widgets:
      #{{github.issue.number}} — {{github.issue.title}}.

      Issue URL: {{github.issue.htmlUrl}}

      Inspect it with issue_read and apply your triage instructions. If it is
      implementation-ready, comment with handoff context, remove the
      `auto-triage` label if present, and spawn Shepherd.
    routing:
      kind: bind
      target: github.issue
      onUnmatched: spawn
  - name: issue-labeled
    event: github.issue.labeled
    connection: github-acme
    where:
      $.github.repository.fullName: acme/widgets
      $.github.auto.authored: false
      $.github.label.name: auto-triage
    message: |
      The `auto-triage` label was just added to acme/widgets
      issue #{{github.issue.number}} — {{github.issue.title}}.

      Issue URL: {{github.issue.htmlUrl}}

      The label is a one-shot re-triage request. Inspect the issue with
      issue_read, apply your triage instructions, then remove the label with
      issue_write once you have acted.
    routing:
      kind: bind
      target: github.issue
      onUnmatched: spawn

.auto/agents/shepherd.yaml

name: shepherd
model:
  provider: anthropic
  id: claude-opus-4-8
identity:
  displayName: Shepherd
  username: shepherd
  avatar:
    asset: .auto/assets/patch.png
  description: Owns triaged issues through implementation, review, and final status reporting.
imports:
  - ../fragments/environments/agent-runtime.yaml
systemPrompt: |
  You are the Shepherd implementation owner for acme/widgets.

  Treat each run as fresh, scoped implementation work. Read the repo's
  contribution docs before editing. Keep the change scoped to the requested
  task; no broad refactors unless required for the fix.

  Work from the mounted checkout on main. Create a feature branch named
  from the issue number plus a short slug, for example
  `auto/issue-123-fix-pagination`.

  Prefer test-first for clear behavior changes: add a focused failing test,
  implement the smallest fix, make it pass. Run the relevant test and
  typecheck commands before opening a PR; document anything you had to skip
  and why.

  Commit with a concise message referencing the issue number, push the
  branch, and open a pull request against main with the create_pull_request
  tool. The PR body must include a Review Map section pointing reviewers at
  the riskiest files first.

  When posting GitHub comments or PRs, append this hidden attribution
  marker with the environment variables expanded:

    <!-- auto:v=1 session_id=$AUTO_SESSION_ID agent=$AUTO_AGENT_NAME -->

  Comment back on the GitHub issue (add_issue_comment) with the PR link, the
  tests you ran, and residual risks.

  If requirements are blocked or tests cannot run, stop and explain the
  blocker instead of inventing a solution.
initialPrompt: |
  Implement the issue described in the spawn message. Follow your profile
  instructions: scoped change, focused tests, a PR against main with a
  Review Map, and a closing comment on the GitHub issue.
mounts:
  - kind: git
    repository: acme/widgets
    mountPath: /workspace/repo
    ref: main
    auth:
      kind: githubApp
      capabilities:
        contents: write
        pullRequests: write
        issues: write
        checks: read
        actions: read
workingDirectory: /workspace/repo
tools:
  auto:
    kind: local
    implementation: auto
  github:
    kind: github
    tools:
      - pull_request_read
      - create_pull_request
      - issue_read
      - add_issue_comment

The permission split is the safety story: triage mounts the repo read-only with issues: write and nothing else (pullRequests: none), while Shepherd gets contents: write and pullRequests: write but is only ever started with a brief that triage already validated. Filtering both GitHub triggers on $.github.auto.authored: false keeps issues opened by auto’s own GitHub App from re-triggering triage in a loop.

Plain-issue comment events use the github.issue.comment.* keys; github.issue_comment.* is GitHub’s PR-comment family. And on GitHub events the authored flag lives at $.github.auto.authored — $.auto.authored is the chat-event path. See GitHub events.

Walkthrough

An issue opens

github.issue.opened arrives; issue-opened matches. No session is bound to this issue, so onUnmatched: spawn starts a triage session bound to the github.issue target.

Triage acts on the issue

The session inspects the issue with issue_read, checks for duplicates, sets the most specific existing labels and a priority with issue_write (it never creates labels), and posts one comment explaining what it did — or asking for reproduction steps and acceptance criteria when the report is too thin.

A human requests a re-pass

Later, someone adds the auto-triage label. github.issue.labeled with $.github.label.name: auto-triage matches; the bind route delivers into the still-live triage session, or spawns a fresh one bound to the issue if the original is gone. Triage acts, then removes the label — consuming the token.

Handoff to Shepherd

When the issue is implementation-ready, triage comments handoff context on the issue, removes the label, and calls auto.sessions.spawn with agent: shepherd and the full brief. The tool returns the new session (with its URL), so the handoff is traceable from either session.

Shepherd ships a PR

The Shepherd session boots with the repo mounted at main, creates auto/issue-123-…, works test-first, pushes, opens a PR with a Review Map via create_pull_request, and closes the loop with add_issue_comment: PR link, tests run, residual risks. If a code review agent is installed, it picks the PR up from github.pull_request.opened.

Linear variant

Teams that track work in Linear import the -linear entrypoints. The shape changes in three ways: the trigger source becomes linear.issue.* events, the label is the only request token (there is no every-new-issue trigger), and issue metadata is read and mutated through the unified chat tool’s chat.issue.get / chat.issue.update instead of the GitHub tool.

.auto/agents/issue-triage.yaml

name: issue-triage
imports:
  - "@auto/agents@latest/issue-triage-linear.yaml"
variables:
  repoFullName: acme/widgets
  linearConnection: linear

The Linear triggers fire on creation with the label present, and on update only when the label was just added — linear.updatedFrom.labelNames.added carries exactly the labels the update added:

triggers:
  - name: issue-created
    event: linear.issue.created
    connection: linear
    where:
      $.linear.issue.labelNames:
        contains: auto-triage
    routing:
      kind: spawn
  - name: issue-labeled
    event: linear.issue.updated
    connection: linear
    where:
      $.linear.updatedFrom.labelNames.added:
        contains: auto-triage
    routing:
      kind: spawn

Payload placeholders follow the Linear namespace: {{linear.issue.identifier}}, {{linear.issue.title}}, {{linear.issue.url}}. Shepherd still needs the GitHub App mount to open PRs; it reports back on the Linear issue via chat.send with target provider linear. See Linear events.

Variations

Slack visibility. The managed template’s base entrypoints already carry optional: true Slack wiring — an ad-hoc @mention trigger on each agent plus triage’s ready-work notes in #dev — which apply skips while no slack connection exists and activates on the next apply once one does. The handwritten configuration above keeps triage’s chat tool but trims the mention triggers; copy the mention trigger from the code review example to restore them.
Direct coding handoffs. For “just fix it” requests on issues (a human mentions the handoff agent in an issue comment), the handoff example is purpose-built: it keeps the issue binding, opens a PR, binds it as github.pull_request, and reports back on the issue.
Raise or lower the handoff bar. The definition of “implementation-ready” lives entirely in the triage systemPrompt. Tighten it (require acceptance criteria and a reproduction) for riskier codebases; loosen it for internal tools.
Guard the spend. Add spendCaps to shepherd (for example spendCaps: { maxPerSessionUsd: "10" }) so a runaway implementation session self-limits.
Smoke test. After apply, open a test issue and confirm a triage session spawns and comments. Then label an implementation-ready issue auto-triage and watch Shepherd open a PR. You can also start either agent directly from the web app with a message like “Triage issue #42”.

Get Started

Concepts

Examples

Reference

Issue Triage

How it works

Install from the managed template

The full configuration

Walkthrough

Linear variant

Variations

​How it works

​Install from the managed template

​The full configuration

​Walkthrough

​Linear variant

​Variations

How it works

Install from the managed template

The full configuration

Walkthrough

Linear variant

Variations