@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.4

package/templates/packs/github/files/.github/workflows/claude-pr-review.yml

@@ -0,0 +1,267 @@
+name: Claude PR Review
+
+# What this does: reviews every pull request when it's opened, pushed to,
+# marked ready or reopened, checking the same things a human reviewer would
+# (see the prompt below), then posts the result as one sticky summary comment
+# plus inline comments. It never approves, blocks, or pushes code, and it
+# skips bot-authored and fork pull requests.
+#
+# Two jobs, because Claude does not post the review itself. `review` runs
+# Claude read-only and gets its findings back as schema-validated structured
+# output (`--json-schema`); `post` is plain `gh` + `jq` and is the only job
+# holding `pull-requests: write`. Letting the model post through `gh pr
+# comment` or the inline-comment MCP tool fails silently and green: runs
+# complete successfully with real spend and permission denials and post
+# nothing, so a new push looks unreviewed until the PR is closed and
+# reopened. The trigger is not the problem -- `synchronize` and `reopened`
+# both start runs. Likely cause: the action loads the repository's own
+# `.claude/` and CLAUDE.md, and a project that documents subagent workflows
+# makes the model dispatch review subagents that have no MCP tool and no
+# `gh api`; background subagents also end the action's run at the first
+# result message. Upstream reports the same shape: claude-code-action#1523
+# (success, nothing posted), #1823 (a `--edit-last` re-review silently
+# skipped), #1852/#1499/#1646 (background subagents), #1679 (the buffered
+# inline-comment step exits 0 after posting nothing). There is no input that
+# fails a run which posted nothing, and `use_sticky_comment` does nothing in
+# this mode, so posting moved out of the model: without `structured_output`
+# the action itself fails the run (docs/usage.md), and the `post` job fails
+# on any API error other than an inline comment GitHub can't anchor
+# (HTTP 422), which is folded into the summary instead.
+#
+# One run is deliberately skipped: claude-code-action will not run on a PR
+# that edits this very file (its copy must match the default branch's, a
+# guard against a PR rewriting its own reviewer). It logs a warning and exits
+# success with no outputs, so the `gate` step tells that case apart from a
+# real empty result -- no `conclusion` AND this file differs from the base --
+# and `post` is skipped with a notice. Any other empty result fails `review`.
+# A PR touching this file therefore gets no review until it merges.
+#
+# `--disallowedTools` keeps subagents and writes off in `review`, and the job
+# has no write token at all (contents/pull-requests read), so a prompt
+# injected through a PR's contents can at worst return a wrong review, not
+# post, push or approve. A review is never a formal GitHub review either
+# (Anthropic's own docs/capabilities-and-limitations.md), so it cannot
+# satisfy or bypass any branch-protection required check or approval count.
+# Comments appear as github-actions[bot] rather than claude[bot]. Excludes
+# bot-authored and fork PRs explicitly below, rather than relying on
+# anthropics/claude-code-action's own internal bot/permission checks
+# (docs/security.md) -- that way a Dependabot or fork PR never starts a run
+# that would just fail on missing secrets. Runs but fails cleanly on an auth
+# error until the one-time setup described in claude.yml's comments is done
+# by hand.
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+
+# Cancel a stale run when the PR gets a new push, same as this project's own
+# CI -- a `synchronize` fires on every push, and a paid review run per push
+# queues up otherwise. This also cancels a `post` job still running for the
+# old head.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Reset, then grant per job.
+permissions: {}
+
+jobs:
+  review:
+    if: |
+      github.event.pull_request.user.type != 'Bot' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      pull-requests: read
+      id-token: write # see claude.yml for why this is needed regardless of auth method
+    outputs:
+      review: ${{ steps.claude.outputs.structured_output }}
+      skipped: ${{ steps.gate.outputs.skipped }}
+    steps:
+      # Full history, not depth 1: the prompt tells Claude to `git diff` the
+      # base against the head, and a shallow clone has no base to diff.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - id: claude
+        uses: anthropics/claude-code-action@ed670b4cf9de2a5a570d130d2f6197b9e543cd64 # v1.0.240
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          # Swap in CLAUDE_CODE_OAUTH_TOKEN or the Workload Identity
+          # Federation inputs instead -- see claude.yml's comments for all
+          # three auth options; this workflow needs the same one configured.
+
+          # Pinned rather than left on the action's default: there is no
+          # `model:` input (anthropics/claude-code-action's action.yml has
+          # none), the action's own docs defer the default's definition to
+          # a separate page rather than naming it, and no official source
+          # states whether that default can change between action releases
+          # -- an automated, unattended job like this one is exactly where a
+          # silent shift would go unnoticed.
+          #
+          # `--fallback-model` (both `model:` and `fallback_model:` are
+          # deprecated action inputs -- claude-code-action's docs/usage.md
+          # says to configure both through `claude_args` now) tries the
+          # listed model only when the primary is overloaded, unavailable,
+          # or returns another non-retryable server error -- never for an
+          # auth, billing, rate-limit, request-size, transport, or
+          # org-policy failure, a real, currently-unfixed gap
+          # (anthropics/claude-code-action#594, redirected to and
+          # auto-closed `not_planned` as anthropics/claude-code#8413) -- but
+          # worth having for the failure mode it does cover.
+          #
+          # `--allowedTools` is read-only on purpose: the diff and PR
+          # metadata, plus git history (Read/Grep/Glob are allowed by
+          # default). `--disallowedTools` removes subagents and every write.
+          # `--json-schema` makes the result machine-readable: the action
+          # fails the step when Claude returns no `structured_output`.
+          claude_args: |
+            --model claude-opus-5-5
+            --fallback-model claude-sonnet-5-5
+            --allowedTools "Bash(gh pr diff:*),Bash(gh pr view:*),Bash(git diff:*),Bash(git log:*),Bash(git show:*)"
+            --disallowedTools "Agent,Task,Write,Edit,NotebookEdit"
+            --json-schema '{"type":"object","properties":{"summary":{"type":"string"},"inline":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"line":{"type":"integer"},"body":{"type":"string"}},"required":["path","line","body"],"additionalProperties":false}}},"required":["summary","inline"],"additionalProperties":false}'
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+            BASE: origin/${{ github.base_ref }}
+            HEAD: ${{ github.event.pull_request.head.sha }}
+            PREVIOUSLY REVIEWED HEAD (empty unless this is a push to an
+            already-open PR): ${{ github.event.before }}
+
+            Review this PR. You already have this repository's CLAUDE.md
+            loaded -- use it, don't restate it. Do not dispatch subagents
+            and do not try to post anything to GitHub: you have no write
+            access, and your only output is the structured result described
+            below. Specifically check:
+
+            1. If this project's CLAUDE.md documents a hub-and-spoke
+               workflow for src/tests changes (test-author before
+               code-implementer, review spokes run over the diff), judge
+               from the PR description and commit history whether it was
+               followed, and say what you could and could not establish
+               rather than guessing.
+            2. Anything the project's own code-review checklist would catch
+               (`.claude/agents/code-reviewer.md`, if present): correctness,
+               security, SOLID/simplification, test coverage.
+            3. If this project uses changesets or another release-versioning
+               convention CLAUDE.md documents, whether this PR's public-
+               surface change carries the entry that convention requires.
+
+            Note: the PR branch is already checked out in the current
+            working directory with full history. Read the change with
+            `git diff BASE...HEAD` (or `gh pr diff`).
+
+            Return exactly the structured result:
+            - `summary`: one markdown summary covering every check above
+              (say so explicitly for a check that passes, or that doesn't
+              apply to this project), always non-empty. It always covers
+              the whole PR, not just the latest push.
+            - `inline`: specific code issues, each with the file `path`, the
+              1-based `line` in the new version of that file, and a
+              `body`. Use an empty array when there are none. When
+              PREVIOUSLY REVIEWED HEAD is set, limit these to lines changed
+              since that commit (`git diff <previous>..HEAD`), because
+              earlier findings are already on the PR. Only use lines that
+              appear in the diff, since GitHub rejects any other.
+
+      # claude-code-action refuses to run on a PR that edits its own workflow
+      # file (the file must match the default branch's copy), logs a warning
+      # and still exits success with no outputs -- a green job with no review.
+      # That one case is expected, so it is detected by two independent facts:
+      # the action set no `conclusion` AND this PR really changes this file.
+      # Any other empty result is a failure, never a quiet pass.
+      - id: gate
+        env:
+          CONCLUSION: ${{ steps.claude.outputs.conclusion }}
+          REVIEW: ${{ steps.claude.outputs.structured_output }}
+          BASE: origin/${{ github.base_ref }}
+        run: |
+          set -euo pipefail
+          if [ -n "$REVIEW" ]; then
+            echo "skipped=false" >>"$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ -z "$CONCLUSION" ] \
+            && ! git diff --quiet "$BASE" HEAD -- .github/workflows/claude-pr-review.yml; then
+            echo "::notice::Claude was skipped: this PR edits claude-pr-review.yml, so claude-code-action will not run it until it merges. No review is posted."
+            echo "skipped=true" >>"$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "::error::Claude returned no structured review (conclusion: '${CONCLUSION:-none}')."
+          exit 1
+
+  post:
+    needs: review
+    if: needs.review.result == 'success' && needs.review.outputs.skipped != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pull-requests: write
+    steps:
+      # Everything attacker-influenced (the review JSON, comment bodies) goes
+      # through `env:` and is only ever quoted as a variable, never
+      # interpolated into the script text.
+      - name: Post the review
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          REVIEW: ${{ needs.review.outputs.review }}
+        run: |
+          set -euo pipefail
+          marker='<!-- claude-pr-review -->'
+          me='github-actions[bot]'
+
+          # A review without a summary is a failure, not an empty comment.
+          jq -e '(.summary | type == "string" and length > 0) and (.inline | type == "array")' \
+            <<<"$REVIEW" >/dev/null
+
+          # Inline comments first, so any that can't be anchored land in the
+          # summary. Skip a finding already on the PR from an earlier push.
+          existing=$(mktemp)
+          gh api --paginate "repos/$REPO/pulls/$PR/comments" \
+            --jq ".[] | select(.user.login == \"$me\") | [.path, (.line // .original_line), .body] | @json" \
+            >"$existing"
+          unanchored=$(mktemp)
+          err=$(mktemp)
+          while IFS= read -r finding; do
+            path=$(jq -r '.path' <<<"$finding")
+            line=$(jq -r '.line' <<<"$finding")
+            body=$(jq -r '.body' <<<"$finding")
+            key=$(jq -cn --arg p "$path" --argjson l "$line" --arg b "$body" '[$p, $l, $b]')
+            if grep -Fxq -- "$key" "$existing"; then
+              continue
+            fi
+            if ! gh api -X POST "repos/$REPO/pulls/$PR/comments" \
+              -f body="$body" -f commit_id="$HEAD_SHA" -f path="$path" \
+              -F line="$line" -f side=RIGHT >/dev/null 2>"$err"; then
+              # 422: the line isn't part of the diff. Anything else is real.
+              grep -q 'HTTP 422' "$err" || { cat "$err" >&2; exit 1; }
+              printf -- '- `%s:%s` -- %s\n' "$path" "$line" "$body" >>"$unanchored"
+            fi
+          done < <(jq -c '.inline[]' <<<"$REVIEW")
+
+          # One sticky summary: edit the marked comment, else create it.
+          summary=$(mktemp)
+          {
+            printf '%s\n' "$marker"
+            printf '_Reviewed commit `%s`._\n\n' "${HEAD_SHA:0:7}"
+            jq -r '.summary' <<<"$REVIEW"
+            if [ -s "$unanchored" ]; then
+              printf '\n### Findings that could not be anchored to a diff line\n\n'
+              cat "$unanchored"
+            fi
+          } >"$summary"
+          id=$(gh api --paginate "repos/$REPO/issues/$PR/comments" \
+            --jq ".[] | select(.user.login == \"$me\" and (.body | startswith(\"$marker\"))) | .id" \
+            | tail -n 1)
+          if [ -n "$id" ]; then
+            gh api -X PATCH "repos/$REPO/issues/comments/$id" -F body=@"$summary" >/dev/null
+          else
+            gh api -X POST "repos/$REPO/issues/$PR/comments" -F body=@"$summary" >/dev/null
+          fi

package/templates/packs/github/files/.github/workflows/claude.yml

@@ -0,0 +1,106 @@
+name: Claude Code
+
+# Anthropic's official Claude Code GitHub Action (anthropics/claude-code-action),
+# in interactive mode: responds to @claude mentions on issues, PR reviews,
+# and review comments. Claude commits to a branch and links back to a
+# PR-creation page -- it never opens a PR itself.
+#
+# Want automated review on every PR too? That's a separate workflow, not a
+# block to uncomment here (a second `on:`/`jobs:` in one file would collide
+# the moment it's uncommented) -- see Anthropic's own
+# examples/pr-review-comprehensive.yml:
+# https://github.com/anthropics/claude-code-action/blob/main/examples/pr-review-comprehensive.yml
+#
+# This workflow needs one of the three auth methods below (Option 1 is
+# active by default) -- until one is configured it fails cleanly on an
+# @claude mention (an auth error, not a crash or a silent no-op).
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+# Reset, then grant per job.
+permissions: {}
+
+jobs:
+  claude:
+    # Issues and comments are open to anyone on a public repository, so the
+    # `@claude` text match alone would let an outside commenter trigger a job
+    # holding `contents: write` and your auth secret. Each branch below also
+    # requires the `author_association` of the comment's, review's or
+    # issue's author to be OWNER, MEMBER or COLLABORATOR. Two consequences:
+    # an org member whose membership is private can surface as CONTRIBUTOR
+    # and be skipped, and on `issues` the check is on the issue's author, not
+    # on whoever assigned it, so assigning an outsider's issue does not start
+    # a run.
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude') && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.review.author_association)) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')) && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.issue.author_association))
+    # One run per issue/PR at a time. A later @claude mention queues behind
+    # the run in flight without cancelling it; GitHub keeps only the latest
+    # pending run per group, so a burst of mentions can drop the middle ones.
+    concurrency:
+      group: claude-${{ github.event.issue.number || github.event.pull_request.number }}
+      cancel-in-progress: false
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      # Required even with a static API key: the default GitHub App
+      # authentication path uses this to fetch a GitHub OIDC token for its
+      # own token exchange, separate from how the action authenticates to
+      # Anthropic.
+      id-token: write
+      actions: read # lets Claude read CI results on the PR it's tagged in
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        uses: anthropics/claude-code-action@ed670b4cf9de2a5a570d130d2f6197b9e543cd64 # v1.0.240
+        with:
+          # Option 1 (active default): a stored API key. Install the Claude
+          # GitHub App (https://github.com/apps/claude) and add
+          # ANTHROPIC_API_KEY as a repository secret.
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+
+          # Commit through the GitHub API instead of local `git`, so GitHub
+          # signs the commits -- a branch ruleset requiring signed commits
+          # would otherwise reject whatever this job pushes.
+          use_commit_signing: true
+
+          # Option 2: a Claude subscription's OAuth token instead of an API
+          # key -- generate once locally with `claude setup-token`, then add
+          # it as CLAUDE_CODE_OAUTH_TOKEN and swap it in for the line above.
+          # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # Option 3: Workload Identity Federation -- no stored secret at
+          # all, exchanges this workflow's GitHub OIDC token for a
+          # short-lived Anthropic token. Needs a one-time setup in the
+          # Anthropic Console (Settings -> Workload identity): register a
+          # GitHub Actions issuer, create a service account, create a
+          # federation rule. Then replace anthropic_api_key above with:
+          # anthropic_federation_rule_id: fdrl_xxxxxxxxxxxx
+          # anthropic_organization_id: 00000000-0000-0000-0000-000000000000
+          # anthropic_service_account_id: svac_xxxxxxxxxxxx
+
+          # Optional: customize the trigger phrase (default: @claude)
+          # trigger_phrase: "/claude"
+
+          # Optional: configure Claude's behavior with CLI arguments
+          # claude_args: |
+          #   --max-turns 10
+          #   --allowedTools "Bash(npm install),Bash(npm run build),Bash(npm run test:*)"

package/templates/packs/github/pack.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "name": "github",
+  "description": "GitHub-hosted collaboration on top of the baseline: Anthropic's official Claude Code GitHub Action (anthropics/claude-code-action) wired for @claude mention-mode, a second Action that posts an automated Claude review comment on every PR, and three gh-CLI skills -- reviewing-dependabot-prs (classify and batch-merge open Dependabot PRs), triaging-scan-alerts (triage open code-scanning alerts to file:line, report only), and watching-pr-checks (check a PR's CI status and hand off to a project's own /triaging-ci on a real failure).",
+  "modes": ["fresh", "adopt"],
+  "budget": {
+    "agents": 0,
+    "skills": 3,
+    "hooks": 0,
+    "workflows": 2,
+    "scripts": 0
+  },
+  "wiring": {
+    "settings": {},
+    "packageScripts": {},
+    "verifySteps": []
+  },
+  "adoptNotes": "claude.yml only reacts to @claude mentions from a repository owner, member or collaborator (author_association), so an outside commenter on a public repository cannot start a job that holds contents: write and your auth secret; an org member with private membership may surface as CONTRIBUTOR and be skipped. It also commits through the GitHub API (use_commit_signing) so a signed-commits ruleset accepts its work. Both workflows need one thing this pack cannot verify or install: an ANTHROPIC_API_KEY repository secret (the active default), or a CLAUDE_CODE_OAUTH_TOKEN from a Claude subscription, or a Workload Identity Federation setup in the Anthropic Console -- see the comments in .github/workflows/claude.yml for all three. Until one is configured, either workflow runs and fails cleanly (an auth error in the run log, not a crash and not a silent no-op): claude.yml on an @claude mention, claude-pr-review.yml on the next PR open/push. An adopted project that already has its own .github/workflows/claude.yml or claude-pr-review.yml surfaces as an ordinary file conflict -- keep the existing one if it's already configured for that project's own auth choice, since this pack's version would just overwrite a working setup with its own generic defaults. triaging-scan-alerts reads code-scanning alerts, and nothing in the baseline or this pack produces them: turn on GitHub's CodeQL default setup for the repository (Settings > Code security), or install the `publishing` pack, whose scorecard.yml uploads SARIF, otherwise the skill's first call returns \"code scanning is not enabled\" and reports nothing. The other two skills have no such dependency: they install anywhere a .claude/ directory exists and need only `gh` CLI auth (already required by every other gh-CLI-based skill this baseline ships). watching-pr-checks' handoff to /triaging-ci degrades gracefully if the project doesn't have that skill installed -- it still reports the real failure, just without the handoff."
+}