@groupby/ai-dev 0.5.5 → 0.5.8

package/teams/snpd/skills/code-review-github/SKILL.md

@@ -0,0 +1,475 @@
+---
+name: code-review-github
+description: Use when the user wants to add Claude Code Agent + GitHub Copilot AI tooling to a repository — automatic PR code review, on-demand `@claude` assistance, a Copilot setup workflow, a structured PR template, and AI context files (`CLAUDE.md`, `.github/copilot-instructions.md`, `docs/*`). Triggered by `/code-review-github` or requests like "set up Claude PR review", "add the AI agent setup", "configure the copilot workflows", "bootstrap AI agents in this repo". Originally built for GroupBy Java/Micronaut repos but adapts to any stack.
+---
+
+# code-review-github
+
+Bootstrap a repository with the standard Claude Code Agent + GitHub Copilot
+setup: GitHub Actions for automatic PR review and `@claude` assistance, a
+Copilot environment-setup workflow, a PR template with an AI checklist, and the
+AI context files agents read on every session.
+
+This skill is **self-contained** — every file template lives below, verified
+against a working reference implementation. Do not fetch anything external.
+
+## What this setup provides
+
+| Capability | Tool | Trigger |
+|---|---|---|
+| Automatic PR code review | Claude Code | PR opened |
+| On-demand AI assistance | Claude Code | `@claude` in PR comment |
+| Copilot workspace environment | GitHub Copilot | workflow_dispatch / file change |
+| Structured PR descriptions | PR template | PR creation |
+| AI context for IDE Copilot | `copilot-instructions.md` | IDE session |
+| AI context for Claude | `CLAUDE.md` | Claude session |
+
+## Files this skill creates or updates
+
+| # | File | Action | Project-specific? |
+|---|---|---|---|
+| 1 | `.github/workflows/claude.yml` | Create | No — copy verbatim |
+| 2 | `.github/workflows/claude-pr-review.yml` | Create | Yes — tune review prompt |
+| 3 | `.github/workflows/copilot-setup-steps.yml` | Create | Yes — match build/runtime |
+| 4 | `.github/PULL_REQUEST_TEMPLATE.md` | Create | Yes — Jira/issue prefix |
+| 5 | `.github/copilot-instructions.md` | Create | Yes — full rewrite |
+| 6 | `CLAUDE.md` | Create | Yes — full rewrite |
+| 7 | `.gitignore` | Update | No — append AI section |
+| 8 | `docs/source-control.md` | Create | No — universal |
+| 9 | `docs/project-rule.md` | Create | Yes — tune tech rules |
+| 10 | `docs/project-structure.md` | Create | Yes — full rewrite |
+| 11 | `docs/<service-name>.md` | Create | Yes — main service doc |
+
+## Procedure
+
+### 1. Scan the repo first — never guess
+
+Before writing anything, gather the facts that drive the project-specific files:
+
+- **Build & runtime:** `build.gradle`/`pom.xml`/`package.json`/`go.mod`/etc. —
+  language + version, framework, build commands, test commands.
+- **Submodules:** check for `.gitmodules`. Drives whether the Copilot workflow
+  needs `submodules: recursive` and a `GIT_TOKEN`.
+- **Issue tracker prefix:** infer from existing branch names / commit history
+  (e.g. `S4R-`, `PROJ-`). Drives the PR template link.
+- **Existing files:** if any target file already exists, read it and propose a
+  merge rather than overwriting. Never clobber a hand-maintained `CLAUDE.md`.
+- **CI:** existing `.github/workflows/` — note the runner, JDK/Node version,
+  and cache strategy already in use so the Copilot workflow matches.
+
+Announce what you found and what you intend to create before writing.
+
+### 2. Confirm prerequisites with the user
+
+These are configured outside the repo and the skill cannot do them. List them
+and ask the user to confirm they are (or will be) set:
+
+- **GitHub secret `ANTHROPIC_API_KEY`** — from console.anthropic.com.
+- **GitHub secret `GIT_TOKEN`** — a PAT with `contents:read`, only if the repo
+  uses submodules.
+- **Claude GitHub App** installed for the repo
+  (https://github.com/apps/claude) with `contents:read` and
+  `pull_requests:write`.
+- **Branch protection** on the default branch: require PR before merge, require
+  status checks, allow GitHub Actions to create/approve PRs.
+
+### 3. Create the workflow files (verbatim templates below)
+
+Write files 1–3 from the templates in the **Templates** section. Apply the
+✏️ edits noted there: review focus areas, JDK/Node version, submodule handling,
+and the build/dependency command.
+
+### 4. Create the PR template
+
+Write `.github/PULL_REQUEST_TEMPLATE.md` from the template, replacing the
+issue-tracker prefix with the one detected in step 1.
+
+### 5. Update `.gitignore`
+
+Append the AI section from the template. Skip any line already present (e.g.
+don't add `/.cursor/` if `.cursor` already appears).
+
+### 6. Create the documentation files
+
+- `docs/source-control.md` — copy verbatim (universal).
+- `docs/project-rule.md` — copy, then tune the tech-specific lines (language
+  version, framework name).
+- `docs/project-structure.md` — write from the repo scan: top-level layout,
+  main source packages and their purpose, test layout, key config files.
+- `docs/<service-name>.md` — write for the main service/entry point: main
+  endpoint, request flow, key methods, dependencies, feature flags, error
+  handling.
+
+### 7. Write the AI context files (`CLAUDE.md` + `copilot-instructions.md`)
+
+These are fully project-specific and mirror each other. **Verify every claim**
+against source before including it: confirm each build/test command exists,
+quote exact config keys, list directories before describing them, and never
+instruct placing credentials in a repo-tracked file (use `~/.gradle/...`,
+`~/.m2/...`, `~/.npmrc`, or env vars). Keep `CLAUDE.md` a thin index that points
+into `docs/`. Use the skeletons in the Templates section.
+
+If the repo already follows the `docs-init` canonical structure (architecture /
+local-setup / conventions / operations / decisions), point `CLAUDE.md` at those
+files instead of inventing new ones — don't duplicate.
+
+### 8. Verify
+
+Run through the checklist and report status to the user:
+
+- [ ] `ANTHROPIC_API_KEY` secret set (and `GIT_TOKEN` if submodules used).
+- [ ] Claude GitHub App installed for the repo.
+- [ ] `copilot-setup-steps.yml` job is named exactly `copilot-setup-steps`.
+- [ ] Review prompt tuned to the project's real concerns.
+- [ ] JDK/Node version in the Copilot workflow matches the build file.
+- [ ] All `docs/*.md` exist and the links in `CLAUDE.md` resolve.
+- [ ] Suggest a test PR to confirm `claude-pr-review.yml` triggers and posts,
+      and an `@claude` comment to confirm `claude.yml` triggers.
+- [ ] Suggest a commit message (e.g. `chore: add Claude Code + Copilot AI setup`).
+
+## Hard rules
+
+- **Never overwrite an existing hand-maintained file silently.** Read it,
+  propose a merge, confirm.
+- **The Copilot job MUST be named `copilot-setup-steps`** or Copilot won't pick
+  it up.
+- **Verify every command and config key** in `CLAUDE.md` /
+  `copilot-instructions.md` against source. Don't fabricate tasks.
+- **Never put credentials in repo-tracked files.** Secrets live in GitHub
+  Actions secrets; local creds live in user-home config.
+- **Pin the action and model versions** as written; only bump when the user
+  asks. Update the `--model` value if the user wants a specific model.
+- **`submodules: recursive` + `GIT_TOKEN`** only if the repo actually has
+  submodules — remove both otherwise.
+
+---
+
+## Templates
+
+### 1. `.github/workflows/claude.yml` — copy verbatim
+
+```yaml
+name: Claude Code
+
+# Triggers: new PR opened or @claude mentioned in a PR comment
+on:
+  pull_request:
+    types: [ opened ]
+  issue_comment:
+    types: [ created ]
+
+# Cancel redundant runs on the same PR
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  claude:
+    name: Run Claude Code Agent
+    # Run on new PRs or when @claude is mentioned in a PR comment
+    if: |
+      (github.event_name == 'pull_request' && github.event.action == 'opened') ||
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request && contains(github.event.comment.body, '@claude'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ github.token }}
+          claude_args: |
+            --model claude-opus-4-5
+```
+
+### 2. `.github/workflows/claude-pr-review.yml` — ✏️ tune the `prompt` focus areas
+
+```yaml
+name: Claude Code PR Review
+
+# Triggers: new PR opened or @claude mentioned in a PR comment
+on:
+  pull_request:
+    types: [ opened ]
+  issue_comment:
+    types: [ created ]
+
+# Cancel redundant runs on the same PR
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  claude-pr-review:
+    name: Run Claude PR Review
+    # Run on new PRs or when @claude is mentioned in a PR comment
+    if: |
+      (github.event_name == 'pull_request' && github.event.action == 'opened') ||
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request && contains(github.event.comment.body, '@claude'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: PR Review with Progress Tracking
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ github.token }}
+
+          # Enable progress tracking
+          track_progress: true
+
+          # ✏️ UPDATE these focus areas for your project
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Perform a comprehensive code review with the following focus areas:
+
+            1. **Code Quality**
+               - Clean code principles and best practices (Single responsibility principle)
+               - Code clarity, readability and maintainability
+               - Proper error handling and edge cases
+               - Check for unnecessary complexity and nesting
+               - Check for redundant code and abstractions
+               - Ensure consistency with project standards
+               - Check for overly compact or clever code
+
+            2. **Security**
+               - Check for potential security vulnerabilities
+               - Validate input sanitization
+               - Review authentication/authorization logic
+
+            3. **Performance**
+               - Identify potential performance bottlenecks
+               - Review database queries for efficiency
+               - Check for memory leaks or resource issues
+
+            4. **Testing**
+               - Verify adequate test coverage
+               - Review test quality and edge cases
+               - Check for missing test scenarios
+               - Check for superfluous tests
+
+            5. **Documentation**
+               - Ensure code is properly documented
+               - Verify README updates for new features
+               - Check API documentation accuracy
+
+            Provide detailed feedback using inline comments for specific issues.
+            Do not include your todo list in the final review.
+            Use top-level comments for general observations or praise.
+            At the end of the review, add a wit quatrain describing the PR. (Do it only once per PR)
+
+          # Tools for comprehensive PR review
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Read,Glob,Grep,TodoWrite,Task,Skill"
+            --model claude-opus-4-5
+```
+
+### 3. `.github/workflows/copilot-setup-steps.yml` — ✏️ match build/runtime
+
+Java/Gradle reference below. For Node/Python/Go, swap the setup step, cache key,
+and the final "Download dependencies" command (`npm ci`, `pip install -r ...`,
+`go mod download`). **Keep the job name `copilot-setup-steps`.**
+
+```yaml
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set the permissions to the lowest permissions possible needed for your steps.
+    # Copilot will be given its own token for its operations.
+    permissions:
+      contents: read
+
+    steps:
+      - name: Set up JDK 21        # ✏️ UPDATE: language/version (or use setup-node / setup-python / setup-go)
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive    # ✏️ REMOVE this + token line if no submodules
+          fetch-depth: 0
+          token: ${{ secrets.GIT_TOKEN }}
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Cache Gradle packages
+        uses: actions/cache@v4
+        with:
+          key: v1-dependencies-${{ hashFiles('build.gradle') }}
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+
+      - name: Download dependencies
+        run: ./gradlew dependencies   # ✏️ UPDATE: npm ci / pip install / go mod download
+```
+
+### 4. `.github/PULL_REQUEST_TEMPLATE.md` — ✏️ replace the issue-tracker prefix
+
+```markdown
+[S4R-1234](https://rezolvetech.atlassian.net/browse/S4R-1234)
+<!-- ✏️ UPDATE: replace S4R with your Jira/issue project prefix and the base URL -->
+
+## Description
+
+A high-level description of what is changed by this PR.
+
+## Checks
+
+- [ ] Unit Tests
+- [ ] Update 'vault' variables
+- [ ] Feature flag added / updated / removed
+- [ ] Update documentation (diagram, confluence pages, content inside "/docs" directory, swagger)
+
+## AI Development Checklist
+
+- [ ] Spec/requirement linked: <!-- link here -->
+- [ ] AI tool used: <!-- Copilot / @claude / Agent / Other -->
+- [ ] Tests generated/refined with AI
+- [ ] AI review pass completed
+- [ ] Repo context files are still accurate (update if not)
+```
+
+### 5. `.gitignore` — append (skip any line already present)
+
+```gitignore
+# AI docs
+/.claude/
+/.serena/
+/docs/archive/
+/docs/prompts/
+/docs/review/
+/docs/templates/
+```
+
+### 6. `docs/source-control.md` — copy verbatim (universal)
+
+```markdown
+# Source Control
+
+## Branches
+- Branch names must start with the Jira ticket number followed by a short description in kebab-case.
+- Prefixes: `feature/`, `bugfix/`, `hotfix/`, `chore/`
+- Example: `feature/S4R-1234-add-search-caching`
+- `main` is the protected default branch; direct pushes are not allowed.
+
+## Commits
+- Messages must start with the Jira ticket number: `S4R-1234: add search result caching`
+- Write in **imperative mood** and **lowercase** after the ticket prefix.
+- Explain *what* and *why*, not *how*.
+
+## Pull Requests
+- PR title: `S4R-1234: Add result caching for autocomplete`
+- Fill in PR description using the PR template — all checklist items must be reviewed.
+- PRs must be reviewed and approved before merging.
+- Use **Squash and Merge** to keep `main` history clean.
+- Delete the source branch after merging.
+```
+
+### 7. `docs/project-rule.md` — ✏️ tune the tech-specific lines
+
+```markdown
+- Do not look at Linter errors until the user explicitly asks.
+- Do not reformat existing code or imports unrelated to implementation changes.
+- Use `var` for new variables' declaration with new operator.   <!-- ✏️ language-specific -->
+- Use the same naming and style patterns as in the existing code.
+- Use Java 21 with preview features for all new code.            <!-- ✏️ UPDATE language/version -->
+- <Framework> is used as the framework. Check official docs for actual APIs.  <!-- ✏️ UPDATE -->
+- Ensure app build and tests pass before committing any changes.
+```
+
+### 8. `CLAUDE.md` — thin index, fully project-specific
+
+```markdown
+# CLAUDE.md
+
+## Project Overview
+<2-3 sentences: what the service does, framework, main purpose>
+
+## Project Guidelines
+- Coding standards: @docs/project-rule.md
+- Project structure: @docs/project-structure.md
+- Source control: @docs/source-control.md
+- <service name> specifics: @docs/<service-name>.md
+- Configuration reference: @docs/configuration-reference.md
+- API reference: @docs/api-reference.md
+
+## Tech Stack
+<table: Framework, Language, Build, Databases, Cache, Messaging, Testing, Monitoring>
+
+## Essential Commands
+<Local Development, Build & Test, Docker — real, verified commands only>
+
+## Architecture
+<Package structure table, request flow, key patterns>
+
+## Critical Logic
+<the most important business logic / algorithm>
+
+## Development Guidelines
+<code style, how to add a feature step-by-step, testing approach>
+
+## Important Files
+<table: file → purpose>
+
+## Local Development Notes
+<prerequisites, credentials (user-home only), environment variables>
+
+## Common Issues
+<table: issue → solution>
+```
+
+### 9. `.github/copilot-instructions.md` — mirrors `CLAUDE.md` for Copilot
+
+Required sections:
+
+1. **Title** — `# AI Coding Agent Instructions for <Project Name>`
+2. **Build, Test, and Development Commands** — all real build-tool commands.
+3. **High-Level Architecture** — core components, integration points, design decisions.
+4. **Development Guidelines** — code style, framework patterns, testing, how to add a service.
+5. **Project Guidelines** — links to `/docs/*.md`.
+6. **Claude Code PR Reviewer Setup** — GitHub config, what Claude reviews, how to disable.