Agent Automation Recipes

name: nightly-dependency-sweep
on:
  schedule:
    - cron: '0 3 * * *'   # 03:00 UTC daily
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  sweep:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Update dependencies
        run: |
          npm update --save
          npm audit fix || true
      - name: Run tests before proposing the bump
        run: npm test --silent
      - name: Open PR if the lockfile changed
        uses: peter-evans/create-pull-request@v6
        with:
          branch: deps/nightly-sweep
          title: 'chore(deps): nightly dependency sweep'
          commit-message: 'chore(deps): nightly dependency sweep'
          body: 'Automated nightly dependency update. Tests passed before this PR was opened.'
          delete-branch: true

name: dependabot-automerge
on:
  pull_request_target:
    types: [opened, reopened, synchronize, ready_for_review]

permissions:
  contents: write
  pull-requests: write

jobs:
  automerge:
    if: github.actor == 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - name: Fetch update metadata
        id: meta
        uses: dependabot/fetch-metadata@v2
      - name: Auto-merge minor and patch updates
        if: steps.meta.outputs.update-type != 'version-update:semver-major'
        run: gh pr merge --auto --squash "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Hold majors for human review
        if: steps.meta.outputs.update-type == 'version-update:semver-major'
        run: |
          gh pr edit "$PR_URL" --add-label 'dependabot-major-held'
          gh pr comment "$PR_URL" --body 'Major version bump held for manual review.'
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: ci-failure-repair
on:
  workflow_run:
    workflows: ['CI']
    types: [completed]

permissions:
  contents: write
  pull-requests: write
  actions: read
  id-token: write

jobs:
  repair:
    # Only on failure, only for PR runs, and never on the fix branch itself.
    if: >-
      github.event.workflow_run.conclusion == 'failure' &&
      github.event.workflow_run.pull_requests[0] &&
      !startsWith(github.event.workflow_run.head_branch, 'claude-auto-fix-ci-')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_branch }}
          fetch-depth: 0
      - name: Create fix branch
        run: git checkout -b "claude-auto-fix-ci-${{ github.run_id }}"
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            The CI workflow failed on this branch. Download the failing job logs
            for run ${{ github.event.workflow_run.id }} with `gh run view`,
            reproduce the failure locally, fix the root cause, and verify the
            build is green. Keep the change minimal.
          claude_args: '--max-turns 15'
      - name: Push the fix branch
        run: git push origin HEAD

name: e2e-failure-healer
on:
  workflow_run:
    workflows: ['E2E Tests']
    types: [completed]

permissions:
  contents: read
  pull-requests: write
  actions: read

jobs:
  heal:
    if: github.event.workflow_run.conclusion == 'failure'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Download the test report artifact
        uses: actions/download-artifact@v4
        with:
          name: e2e-report
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
      - name: Post healing suggestions to the PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const results = JSON.parse(fs.readFileSync('results.json', 'utf8'));
            const failed = results.tests.filter(t => t.status === 'failed');
            if (!failed.length) return;
            const body = ['### E2E healer suggestions', ...failed.map(
              t => `- \`${t.title}\`: check locator \`${t.locator}\` — it may have drifted.`
            )].join('\n');
            const pr = context.payload.workflow_run.pull_requests[0];
            if (pr) await github.rest.issues.createComment({
              ...context.repo, issue_number: pr.number, body
            });

name: pr-review-on-open
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

permissions:
  contents: read
  pull-requests: read
  id-token: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1
      - name: Claude code review
        # SHA-pin the action so a moved @v1 tag can't inject code into CI.
        uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            Review the diff for PR #${{ github.event.pull_request.number }}.
            Focus on correctness bugs, security, and missing tests. Post findings
            as a single PR review comment; do not approve or merge.
          claude_args: '--model claude-opus-4-5'

name: issue-triage
on:
  issues:
    types: [opened]
  workflow_dispatch:
    inputs:
      issue_number:
        description: 'Issue number to triage'
        required: true
        type: string

permissions:
  contents: read
  issues: write
  id-token: write

jobs:
  triage:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Triage this GitHub issue. Classify type (bug/feature/chore/docs),
            suggest labels from `gh label list`, estimate complexity and priority,
            and post a summary table as a comment.
            IMPORTANT: only SUGGEST labels — do not apply them. The maintainer decides.
          claude_args: '--max-turns 3 --model claude-haiku-4-5'

name: ai-skill-maintenance
on:
  schedule:
    - cron: '17 5 * * 1'   # Mondays 05:17 UTC
  workflow_dispatch:
    inputs:
      dry_run:
        description: "Dry run (don't write files)"
        type: boolean
        default: false

permissions:
  contents: write
  pull-requests: write

jobs:
  maintain:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Refresh upstream indices
        run: node scripts/refresh-indices.mjs
      - name: Generate skill updates with the Anthropic SDK
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          AI_DRY_RUN: ${{ inputs.dry_run }}
        run: |
          npm i @anthropic-ai/sdk
          node scripts/ai-generate-updates.mjs
      - name: Validate updates before proposing them
        run: npm run eval:skills
      - name: Open PR if skills changed
        uses: peter-evans/create-pull-request@v6
        with:
          branch: skills/ai-maintenance
          title: 'chore(skills): AI-assisted maintenance update'
          commit-message: 'chore(skills): AI-assisted maintenance update'
          body: 'Automated skill refresh. Eval harness passed before this PR was opened.'
          delete-branch: true

name: weekly-doc-drift
on:
  schedule:
    - cron: '17 6 * * 1'   # Mondays 06:17 UTC
  workflow_dispatch:

permissions:
  contents: read
  issues: write

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Compare live state against the committed baseline
        id: check
        run: |
          # Exit codes form the contract: 0 fresh / 3 drift / 1 hard-fail.
          set +e
          python scripts/check_drift.py --baseline specs/baseline.json
          echo "code=$?" >> "$GITHUB_OUTPUT"
      - name: Open or update a drift issue
        if: steps.check.outputs.code == '3'
        uses: actions/github-script@v7
        with:
          script: |
            const title = 'Spec drift detected';
            const existing = (await github.rest.issues.listForRepo({
              ...context.repo, state: 'open', labels: 'drift'
            })).data[0];
            const body = 'The live catalog no longer matches specs/baseline.json. Review and reconcile.';
            if (existing) await github.rest.issues.update({ ...context.repo, issue_number: existing.number, body });
            else await github.rest.issues.create({ ...context.repo, title, body, labels: ['drift'] });
      - name: Fail loudly on a hard error
        if: steps.check.outputs.code == '1'
        run: 'echo "Drift check could not run (auth/parse error)." && exit 1'

name: stale-entry-hunt
on:
  schedule:
    - cron: '0 4 * * *'   # 04:00 UTC daily
  workflow_dispatch:
    inputs:
      threshold_days:
        description: 'Staleness cutoff (days)'
        type: number
        default: 30

permissions:
  contents: write

jobs:
  hunt:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan for stale entries
        run: |
          python scripts/staleness_scan.py \
            --threshold ${{ inputs.threshold_days || 30 }} \
            --out docs/reports/staleness.md
      - name: Upload the report
        uses: actions/upload-artifact@v4
        with:
          name: staleness-report
          path: docs/reports/staleness.md

name: scheduled-changelog
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 9 * * 1'   # Mondays 09:00 UTC floor
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Run release-please
        uses: googleapis/release-please-action@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          release-type: node

name: security-scan-cron
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 6 * * 1'   # Mondays 06:00 UTC
  workflow_dispatch:

permissions:
  contents: read
  security-events: write

jobs:
  codeql:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/init@v3
        with:
          languages: javascript-typescript
      - uses: github/codeql-action/analyze@v3

  secret-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: stale-issue-sweep
on:
  schedule:
    - cron: '30 1 * * *'   # 01:30 UTC daily
  workflow_dispatch:

permissions:
  issues: write
  pull-requests: write

jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/stale@v9
        with:
          days-before-stale: 30
          days-before-close: 7
          stale-issue-label: stale
          exempt-issue-labels: 'good first issue,help wanted,security,pinned'
          stale-issue-message: 'This issue is stale after 30 days of inactivity. It will close in 7 days without further activity.'
          close-issue-message: 'Closing as stale. Comment to reopen.'
          days-before-pr-stale: -1   # leave PRs alone

name: external-links-check
on:
  schedule:
    - cron: '0 9 * * 1-5'   # 09:00 UTC, weekdays
  workflow_dispatch:

permissions:
  contents: read

jobs:
  links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check external links
        id: check
        run: npx lychee './**/*.md' --exclude-mail
      - name: Notify Slack on failure
        if: failure()
        run: |
          curl -s -X POST -H 'Content-Type: application/json' \
            -d "{\"text\":\"Broken links detected in ${{ github.repository }} — ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\"}" \
            "${{ secrets.SLACK_WEBHOOK_URL }}"

name: scheduled-readme-refresh
on:
  schedule:
    - cron: '0 * * * *'   # hourly
  workflow_dispatch:

permissions:
  contents: write

jobs:
  refresh:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Regenerate README from source data
        run: node scripts/generate-readme.mjs
      - name: Commit only if it changed
        run: |
          if ! git diff --quiet README.md; then
            git config user.name 'github-actions[bot]'
            git config user.email 'github-actions[bot]@users.noreply.github.com'
            git add README.md
            git commit -m 'docs(readme): scheduled refresh [skip ci]'
            git push
          fi

name: upstream-release-watch
on:
  schedule:
    - cron: '0 3 * * *'   # 03:00 UTC daily
  workflow_dispatch:

permissions:
  contents: read
  issues: write

jobs:
  watch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Fetch and diff the upstream changelog
        id: diff
        run: |
          curl -sL https://raw.githubusercontent.com/UPSTREAM/OWNER/main/CHANGELOG.md -o /tmp/upstream.md
          if ! diff -q .cache/upstream-changelog.md /tmp/upstream.md >/dev/null 2>&1; then
            cp /tmp/upstream.md .cache/upstream-changelog.md
            echo 'changed=true' >> "$GITHUB_OUTPUT"
          fi
      - name: Optional LLM triage of the new entries
        if: steps.diff.outputs.changed == 'true' && env.CLAUDE_CODE_OAUTH_TOKEN != ''
        env:
          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
        run: npx @anthropic-ai/claude-code -p --bare 'Summarize the new upstream changelog entries and list which ones require adoption work here.' < /tmp/upstream.md
      - name: File a manual-triage issue as a fallback
        if: steps.diff.outputs.changed == 'true'
        uses: actions/github-script@v7
        with:
          script: |
            await github.rest.issues.create({ ...context.repo,
              title: 'Upstream changelog changed — review for adoption',
              body: 'New upstream entries detected. Review and open adoption tasks as needed.',
              labels: ['upstream-adoption'] });

name: release-readiness-watch
on:
  schedule:
    - cron: '15 16 * * *'   # 16:15 UTC daily
  workflow_dispatch:

permissions:
  contents: read
  issues: write

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Compute release readiness
        id: ready
        run: node scripts/check-release-due.mjs >> "$GITHUB_STEP_SUMMARY"
      - name: Upsert a single tracking issue
        uses: actions/github-script@v7
        with:
          script: |
            const title = 'Release readiness';
            const open = (await github.rest.issues.listForRepo({
              ...context.repo, state: 'open', labels: 'release-watch'
            })).data[0];
            const body = 'See the latest workflow run summary for commit count, proposed version, and npm status.';
            if (open) await github.rest.issues.update({ ...context.repo, issue_number: open.number, body });
            else await github.rest.issues.create({ ...context.repo, title, body, labels: ['release-watch'] });

name: content-validation-sweep
on:
  pull_request:
  schedule:
    - cron: '17 9 * * 1'   # Mondays 09:17 UTC full sweep
  workflow_dispatch:

permissions:
  contents: read

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Schema + policy validation
        run: npm run validate:content
      - name: Build the generated site
        run: npm run build
      - name: Validate registry artifacts
        run: npm run validate:registry

name: spec-consistency-guard
on:
  push:
  pull_request:

permissions:
  contents: read

jobs:
  consistency:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Run the spec-consistency assertions
        run: |
          # Each script asserts one invariant and exits non-zero on violation,
          # so any broken assertion fails the whole job.
          python scripts/validate_schema.py
          python scripts/check_version_consistency.py
          python scripts/check_rubric_weights.py
          python scripts/check_frontmatter.py