Claude boilerplate (#52)

Author: metachris

.github/workflows/claude.yaml

@@ -0,0 +1,112 @@
+name: Claude Assistant
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  pull_request:
+    types: [opened, synchronize] # opened = new PR, synchronize = new commits pushed
+  issues:
+    types: [opened, assigned]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+  id-token: write
+  actions: read # Required for Claude to read CI results on PRs
+
+jobs:
+  # Auto-review for same-repo PRs
+  claude-review:
+    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          track_progress: true # ✨ Enables tracking comments
+          claude_args: |
+            --model opus \
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Act as a code reviewer for this pull request. Focus your review on:
+            - Overall code quality and adherence to best practices
+            - Possible bugs, edge cases, or logical errors
+            - Security concerns or unsafe patterns
+            - Performance characteristics and potential optimizations
+
+            Provide thorough, actionable feedback, and use inline comments for any line-specific issues you identify.
+
+            Note: The PR branch is already checked out in the current working directory.
+
+            Use `gh pr comment` for summary or top-level feedback on the PR.
+            Use `mcp__github_inline_comment__create_inline_comment` to annotate specific code issues inline.
+            Only post GitHub comments - don't submit review text as messages.
+            Use top-level comments for general observations or praise.
+
+  # Manual review triggered by "@claude review" comment (works for forks too)
+  claude-manual-review:
+    if: |
+      github.event_name == 'issue_comment' &&
+      github.event.issue.pull_request &&
+      contains(github.event.comment.body, '@claude review')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Checkout PR branch
+        run: gh pr checkout ${{ github.event.issue.number }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          track_progress: true # ✨ Enables tracking comments
+          claude_args: |
+            --model opus \
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.issue.number }}
+
+            Act as a code reviewer for this pull request. Focus your review on:
+            - Overall code quality and adherence to best practices
+            - Possible bugs, edge cases, or logical errors
+            - Security concerns or unsafe patterns
+            - Performance characteristics and potential optimizations
+
+            Provide thorough, actionable feedback, and use inline comments for any line-specific issues you identify.
+
+            Note: The PR branch is already checked out in the current working directory.
+
+            Use `gh pr comment` for summary or top-level feedback on the PR.
+            Use `mcp__github_inline_comment__create_inline_comment` to annotate specific code issues inline.
+            Only post GitHub comments - don't submit review text as messages.
+            Use top-level comments for general observations or praise.
+
+  # General interactive mode - responds to @claude mentions (but NOT review requests on PRs)
+  claude-response:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && !contains(github.event.comment.body, '@claude review')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') && !contains(github.event.comment.body, '@claude review')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude') && !contains(github.event.review.body, '@claude review')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_args: |
+            --model opus \
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr create:*)"

AGENTS.md

@@ -1,40 +1,52 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-- Source layout: `cmd/cli` and `cmd/httpserver` are entrypoints; shared packages live in `common/`, `httpserver/`, `database/`, and `metrics/`.
-- Tests: co-located `*_test.go` files (e.g., `httpserver/handler_test.go`, `database/database_test.go`).
-- Artifacts: binaries output to `build/` via Makefile targets. Dockerfiles: `cli.dockerfile`, `httpserver.dockerfile`.
-- Go version: 1.24 (see `go.mod`). Module path: `github.com/flashbots/go-template`.
-
-## Coding Style & Naming Conventions
-- Use tabs instead of spaces for indentation.
-- Always run `make fmt` and `make lint` (and `make test`) before committing.
-- Formatting: run `make fmt` before committing. Go files must pass `golangci-lint` (config in `.golangci.yaml`).
-- Style: idiomatic Go; exported identifiers use CamelCase; packages lower-case short names; errors returned, not panicked.
-- JSON tags: prefer snake_case (configured via `tagliatelle`).
-- Logging: use `common.SetupLogger` (slog) and structured fields; respect `--log-json` and `--log-debug` flags.
-
-## Build, Test, and Development Commands
-- `make build`: builds CLI and HTTP server into `build/`.
-- `make build-cli` / `make build-httpserver`: build individual binaries.
-- `make lint`: run formatters and linters (`gofmt`, `gofumpt`, `go vet`, `staticcheck`, `golangci-lint`).
-- `make test` / `make test-race`: run tests (optionally with race detector).
-- `make fmt`: apply formatting (`gofmt`, `gci`, `gofumpt`) and `go mod tidy`.
-- `make cover` / `make cover-html`: coverage summary / HTML report.
-- Docker: `make docker-cli`, `make docker-httpserver` build images using the respective Dockerfiles.
-
-## Testing Guidelines
-- Framework: standard `testing` with `testify/require` for assertions.
-- Run: `make test` (or `go test ./...`).
-- Database tests: gated by `RUN_DB_TESTS=1` and a Postgres instance. Example:
-  - `docker run -d --name postgres-test -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres`
-  - `RUN_DB_TESTS=1 make test`
-- Coverage: aim to keep or increase coverage; use `make cover`.
-
-## Commit & Pull Request Guidelines
-- Commits: concise, imperative mood; scope prefixes like `ci:`, `docs:`, `fix:`, `feat:` when helpful. Reference issues/PRs.
-- PRs: include a clear description, linked issues, test plan (commands run), and any config notes. Ensure `make fmt lint test` pass locally.
-
-## Security & Configuration Tips
-- Configuration: prefer flags/env via `common.GetEnv` and CLI options; avoid hardcoding secrets.
-- HTTP server: `/debug` (pprof) is opt-in; do not expose publicly. Metrics on `/metrics` (Prometheus format).
+This file provides guidance to LLMs when working with code in this repository.
+
+## Build Commands
+
+```bash
+make build-cli        # Build CLI binary to ./build/cli
+make build-httpserver # Build HTTP server binary to ./build/httpserver
+make build            # Build all binaries
+```
+
+## Test Commands
+
+```bash
+make test             # Run all tests
+make test-race        # Run tests with race detector
+go test ./... -run TestName  # Run a single test
+
+# Database tests require a running Postgres instance:
+docker run -d --name postgres-test -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres postgres
+RUN_DB_TESTS=1 make test
+```
+
+## Lint and Format
+
+```bash
+make lint   # Run all linters (gofmt, gofumpt, go vet, staticcheck, golangci-lint)
+make fmt    # Format code (gofmt, gci, gofumpt, go mod tidy)
+make lt     # Run both lint and test
+```
+
+## Architecture
+
+This is a Go project template with two entry points:
+
+- **cmd/cli/main.go** - CLI application entry point using urfave/cli
+- **cmd/httpserver/main.go** - HTTP server entry point with graceful shutdown
+
+### Key Packages
+
+- **httpserver/** - HTTP server with chi router, includes `/livez`, `/readyz`, `/drain`, `/undrain` endpoints, metrics middleware, and optional pprof
+- **database/** - Postgres database layer using sqlx with sql-migrate for migrations
+- **database/migrations/** - In-memory migrations registered in `Migrations` variable
+- **metrics/** - VictoriaMetrics-based Prometheus metrics with HTTP middleware
+- **common/** - Shared utilities including structured logging setup (slog-based via httplog)
+
+### HTTP Server Pattern
+
+The server runs two HTTP servers: main API (default :8080) and metrics (default :8090). Supports graceful shutdown with configurable drain duration for load balancer compatibility.
+
+### Database Migrations
+
+Migrations are defined as Go code in `database/migrations/` and registered in `migrations.Migrations`. They run automatically on database connection unless `DB_DONT_APPLY_SCHEMA` env var is set.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md