AI-Native Delivery: Claude Code Agents, Linear and GitHub Actions

# 1. Install the Claude GitHub App on your repo (run inside Claude Code)
/install-github-app

# 2. Create a token from your Claude subscription and store it as a repo secret
claude setup-token
gh secret set CLAUDE_CODE_OAUTH_TOKEN

# 3. Create the label that dispatches an agent
gh label create claude --color 7C3AED --description "Hand this ticket to an agent"

# .github/agent-protected.txt
# Payment code is human-only. One file feeds two hard layers:
#   1. the agent workflow turns every path into an Edit/Write deny rule
#   2. the guard fails any agent PR whose diff touches a path, model or pattern
#
# Format: a plain line is a path glob (* = one folder, ** = any depth)
#         model: X       protects a model block in prisma/schema.prisma
#         content: <re>  flags any added or removed line that matches

src/lib/stripe.ts
src/app/api/stripe/**
src/lib/billing/**

# The guard itself and CI
.github/**
scripts/agent-guard.mjs

model: Purchase
model: CreditLedger

content: STRIPE_
content: from ["']stripe["']

# .github/workflows/claude-agent.yml
name: Claude agent

on:
  issues:
    types: [labeled]
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  agent:
    # Only the label or an explicit mention. Without this, every comment
    # on every issue boots a runner just to decide there is nothing to do.
    if: |
      (github.event_name == 'issues' && github.event.label.name == 'claude') ||
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude'))
    runs-on: ubuntu-latest
    timeout-minutes: 45
    # One agent per ticket. Different tickets still run in parallel.
    concurrency:
      group: claude-${{ github.event.issue.number || github.event.pull_request.number }}
      cancel-in-progress: false
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write

    # A throwaway database, so the agent can run integration tests.
    # No production secret ever enters this job.
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_USER: app
          POSTGRES_PASSWORD: app
          POSTGRES_DB: app
        ports: ["5432:5432"]

    env:
      DATABASE_URL: postgresql://app:app@localhost:5432/app
      BACKGROUND_AGENT: "1"   # CLAUDE.md switches to its "nobody is watching" rules

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci

      # Every path in agent-protected.txt becomes Edit(path),Write(path)
      - name: Build the agent's deny list
        id: protected
        run: |
          tools=$(grep -vE '^[[:space:]]*(#|$|model:|content:)' .github/agent-protected.txt \
            | sed -E 's/.*/Edit(&),Write(&)/' | paste -sd, -)
          echo "tools=$tools" >> "$GITHUB_OUTPUT"

      - uses: anthropics/claude-code-action@v1
        id: claude
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          label_trigger: claude
          trigger_phrase: "@claude"
          branch_prefix: claude/
          track_progress: true
          # Linear's sync may add the label as its bot, not as you.
          allowed_bots: "linear,linear[bot]"
          claude_args: |
            --max-turns 80
            --disallowedTools "${{ steps.protected.outputs.tools }}"
            --allowedTools "Bash(npm run typecheck),Bash(npm run lint:*),Bash(npm test:*),Bash(git diff:*),Bash(git status),Bash(gh pr create:*)"

## Running as a background agent

When `BACKGROUND_AGENT=1` is set, you were started from a ticket and
nobody is watching. The ticket is the approval.

- **Build, don't ask.** Take the most reasonable reading of the ticket and
  say which one you took. If it is too ambiguous to finish safely, stop and
  post a plan as a comment instead of code.
- **Stay inside the ticket.** No drive-by refactors, no dependency upgrades.
  A small diff is a reviewable diff.
- **Bugs: failing test first.** Reproduce it, watch it fail, then fix it.
- **Before you finish, run** `npm run typecheck`, `npm run lint`, `npm test`.
- **Payment code is human-only.** Everything in .github/agent-protected.txt
  is off limits. If the ticket needs it, stop and comment what would need
  to change, so a human can do that part by hand.
- **You cannot verify in a browser.** Say so, and list what to click through.
- **Open a draft PR as your last step:**
  `gh pr create --draft --base main --title "[ENG-12] ..." --body "Fixes ENG-12"`

      # Runs after Claude either way. If Claude opened the PR, this does nothing.
      # If it didn't, the script opens it. What must always happen is never
      # left to the agent alone.
      - name: Make sure a draft PR exists
        if: always() && steps.claude.outputs.branch_name != ''
        env:
          GH_TOKEN: ${{ github.token }}
          BRANCH: ${{ steps.claude.outputs.branch_name }}
          ISSUE: ${{ github.event.issue.number }}
          TITLE: ${{ github.event.issue.title }}   # via env, never pasted into the script
        run: |
          ahead=$(gh api "repos/$GITHUB_REPOSITORY/compare/main...$BRANCH" --jq .ahead_by) || ahead=0
          [ "$ahead" = "0" ] && { echo "No commits, nothing to propose."; exit 0; }

          existing=$(gh pr list --head "$BRANCH" --state all --json number --jq '.[0].number')
          [ -n "$existing" ] && { echo "Claude opened #$existing itself."; exit 0; }

          # Linear's bot comments the ticket ID (e.g. ENG-12) on synced issues
          linear_id=$(gh api "repos/$GITHUB_REPOSITORY/issues/$ISSUE/comments" \
            --jq '.[] | select(.user.login | test("linear"; "i")) | .body' \
            | grep -oE '\b[A-Z][A-Z0-9]+-[0-9]+\b' | head -n 1 || true)

          title="$TITLE"
          body="Closes #$ISSUE"
          if [ -n "$linear_id" ]; then
            title="[$linear_id] $TITLE"           # this is what links the PR in Linear
            body="$body"$'\n'"Fixes $linear_id"
          fi

          gh pr create --draft --base main --head "$BRANCH" --title "$title" --body "$body"

# .github/workflows/agent-guard.yml
name: Agent guard

on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  guard:
    name: Agent payment-code guard
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Check the PR stays out of payment code
        env:
          HEAD_BRANCH: ${{ github.head_ref }}
          BASE: origin/${{ github.base_ref }}
        run: |
          # Judge the PR with the guard and rules as they are on main,
          # never the PR's own copy, so a PR cannot weaken its own check.
          git show "$BASE:scripts/agent-guard.mjs" > "$RUNNER_TEMP/agent-guard.mjs"
          git show "$BASE:.github/agent-protected.txt" > "$RUNNER_TEMP/agent-protected.txt"
          node "$RUNNER_TEMP/agent-guard.mjs" "$RUNNER_TEMP/agent-protected.txt" "$BASE" HEAD

// scripts/agent-guard.mjs (core of it; no dependencies)
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";

const [listFile, base, head] = process.argv.slice(2);
const branch = process.env.HEAD_BRANCH ?? "";

// Human branches pass straight through: payment code is theirs to change.
if (!branch.startsWith("claude/")) process.exit(0);

const git = (...args) => execFileSync("git", args, { encoding: "utf8" });

const paths = [];
const patterns = [];
for (const raw of readFileSync(listFile, "utf8").split("\n")) {
  const line = raw.trim();
  if (!line || line.startsWith("#") || line.startsWith("model:")) continue;
  if (line.startsWith("content:")) patterns.push(new RegExp(line.slice(8).trim()));
  else paths.push(line);
}

const globToRegExp = (glob) =>
  new RegExp("^" + glob.split("**").map((part) =>
    part.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join("[^/]*")
  ).join(".*") + "$");

const range = `${base}...${head}`;
const violations = [];

for (const file of git("diff", "--name-only", range).split("\n").filter(Boolean)) {
  const glob = paths.find((p) => globToRegExp(p).test(file));
  if (glob) violations.push(`${file}: protected path (${glob})`);

  // Check every added or removed line against the content patterns
  for (const line of git("diff", "-U0", range, "--", file).split("\n")) {
    if (!/^[+-]/.test(line) || /^(\+\+\+|---)/.test(line)) continue;
    const hit = patterns.find((p) => p.test(line.slice(1)));
    if (hit) violations.push(`${file}: matches ${hit}`);
  }
}

if (violations.length) {
  console.error("Agent PR touches human-only code:\n" + violations.join("\n"));
  process.exit(1);
}