From 25cd322f2c65344db369f9fc97de0ff50889e232 Mon Sep 17 00:00:00 2001 From: Christopher Hicks Date: Tue, 14 Oct 2025 19:28:17 -0700 Subject: [PATCH 1/5] "Claude PR Assistant workflow" --- .github/workflows/claude.yml | 50 ++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 .github/workflows/claude.yml diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml new file mode 100644 index 0000000..b1a3201 --- /dev/null +++ b/.github/workflows/claude.yml @@ -0,0 +1,50 @@ +name: Claude Code + +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + issues: + types: [opened, assigned] + pull_request_review: + types: [submitted] + +jobs: + claude: + if: | + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || + (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read + issues: read + 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: 1 + + - name: Run Claude Code + id: claude + uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + # This is an optional setting that allows Claude to read CI results on PRs + additional_permissions: | + actions: read + + # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it. + # prompt: 'Update the pull request description to include a summary of changes.' + + # Optional: Add claude_args to customize behavior and configuration + # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md + # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options + # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)' + From a61bc3c36cee585db2495e4a3425860895ffe53e Mon Sep 17 00:00:00 2001 From: Christopher Hicks Date: Tue, 14 Oct 2025 19:28:18 -0700 Subject: [PATCH 2/5] "Claude Code Review workflow" --- .github/workflows/claude-code-review.yml | 57 ++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 .github/workflows/claude-code-review.yml diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml new file mode 100644 index 0000000..31c04fd --- /dev/null +++ b/.github/workflows/claude-code-review.yml @@ -0,0 +1,57 @@ +name: Claude Code Review + +on: + pull_request: + types: [opened, synchronize] + # Optional: Only run on specific file changes + # paths: + # - "src/**/*.ts" + # - "src/**/*.tsx" + # - "src/**/*.js" + # - "src/**/*.jsx" + +jobs: + claude-review: + # Optional: Filter by PR author + # if: | + # github.event.pull_request.user.login == 'external-contributor' || + # github.event.pull_request.user.login == 'new-developer' || + # github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' + + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read + issues: read + id-token: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Run Claude Code Review + id: claude-review + uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + prompt: | + REPO: ${{ github.repository }} + PR NUMBER: ${{ github.event.pull_request.number }} + + Please review this pull request and provide feedback on: + - Code quality and best practices + - Potential bugs or issues + - Performance considerations + - Security concerns + - Test coverage + + Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback. + + Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR. + + # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md + # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options + claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"' + From f68c61f727efb633ec5906323db85a983a6b8efe Mon Sep 17 00:00:00 2001 From: Christopher Hicks Date: Tue, 14 Oct 2025 19:29:55 -0700 Subject: [PATCH 3/5] better security --- .github/workflows/claude-code-review.yml | 3 +++ .github/workflows/claude.yml | 3 +++ 2 files changed, 6 insertions(+) diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index 31c04fd..8a64952 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -10,6 +10,9 @@ on: # - "src/**/*.js" # - "src/**/*.jsx" +# global permissions +permissions: {} + jobs: claude-review: # Optional: Filter by PR author diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index b1a3201..e4699ec 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -10,6 +10,9 @@ on: pull_request_review: types: [submitted] +# global permissions +permissions: {} + jobs: claude: if: | From 46a3274ebc6c22584651c2bb1affa8a90b9d930c Mon Sep 17 00:00:00 2001 From: Christopher Hicks Date: Tue, 14 Oct 2025 19:30:31 -0700 Subject: [PATCH 4/5] add /CLAUDE.md --- CLAUDE.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ef16c22 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,76 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Purpose + +This is a GitHub repository template that implements best practices for open source projects. It's designed to be cloned and customized for new repositories. The template includes GitHub community standards compliance, automated workflows, and a command-line driven development process. + +## Development Workflow + +This repo uses `just` (command runner) for all development tasks. The workflow is entirely command-line based using `just` and the GitHub CLI (`gh`). + +### Standard development cycle + +1. `just branch ` - Create a new feature branch (format: `$USER/YYYY-MM-DD-`) +2. Make changes and commit (last commit message becomes PR title) +3. `just pr` - Create PR, push changes, and watch checks (waits 10s for GitHub API) +4. `just merge` - Squash merge PR, delete branch, return to main, and pull latest +5. `just sync` - Return to main branch and pull latest (escape hatch) + +### Additional commands + +- `just` or `just list` - Show all available recipes +- `just prweb` - Open current PR in browser +- `just release ` - Create a GitHub release with auto-generated notes +- `just clean_readme` - Generate a clean README from template (strips template documentation) +- `just compliance_check` - Run custom repo compliance checks +- `just utcdate` - Print UTC date in ISO format (used in branch names) + +### Git aliases used + +The justfile assumes these git aliases exist: + +- `git stp` - Show status (likely `status --short` or similar) +- `git pushup` - Push and set upstream tracking +- `git co` - Checkout + +## Architecture + +### Modular justfile structure + +The main `justfile` imports two modules: + +- `.just/compliance.just` - Custom compliance checks for repo health +- `.just/gh-process.just` - Git/GitHub workflow automation + +### GitHub Actions + +Four workflows run on PRs and pushes to main: + +- **markdownlint** - Enforces markdown standards using `markdownlint-cli2` +- **checkov** - Security scanning for GitHub Actions +- **actionlint** - Lints GitHub Actions workflow files +- **auto-assign** - Automatically assigns issues + +### Markdown linting + +Configuration in `.markdownlint.yml`: + +- MD013 (line length) is disabled +- MD041 (first line h1) is disabled +- MD042 (no empty links) is disabled +- MD004 (list style) enforces dashes +- MD010 (tabs) ignores code blocks + +Run locally: `markdownlint-cli2 **/*.md` + +## Template customization + +When using this template for a new project, search and replace: + +- `fini-net` → your GitHub org +- `template-repo` → your repo name +- `chicks-net` → your references + +Run `just clean_readme` to strip template documentation from README. From 023c2a9c7073790eb6ee9f8686774c91d28b7cd6 Mon Sep 17 00:00:00 2001 From: Christopher Hicks Date: Tue, 14 Oct 2025 19:33:26 -0700 Subject: [PATCH 5/5] add .claude/settings.local.json from www-chicks-net repo --- .claude/settings.local.json | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .claude/settings.local.json diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..d203126 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,19 @@ +{ + "permissions": { + "allow": [ + "WebFetch(domain:www.chicks.net)", + "WebFetch(domain:developers.facebook.com)", + "WebFetch(domain:github.com)", + "WebFetch(domain:raw.githubusercontent.com)", + "WebFetch(domain:en.wikipedia.org)", + "Bash(gh pr view:*)", + "Bash(gh pr diff:*)", + "Bash(git log:*)", + "WebSearch", + "Bash(markdownlint-cli2:*)", + "Bash(identify:*)" + ], + "deny": [], + "ask": [] + } +}