Skip to content

CLAUDE.md

Latest commit

 

History

History
222 lines (172 loc) · 7.64 KB

CLAUDE.md

File metadata and controls

222 lines (172 loc) · 7.64 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Purpose

This is the zircote/.github organization-wide repository providing shared GitHub infrastructure:

  • Community health files (SECURITY.md, CONTRIBUTING.md)
  • Reusable GitHub Actions workflows
  • Composite actions for CI/CD
  • Copilot skills and autonomous agents
  • Label definitions and templates

Repository Structure

.github/
├── .github/
│   ├── workflows/           # Reusable workflows (workflow_call)
│   ├── skills/              # Copilot skills (SKILL.md format)
│   ├── prompts/             # GitHub Copilot prompts
│   └── ISSUE_TEMPLATE/      # Issue templates
├── actions/                 # Composite actions
│   ├── setup-python-uv/     # Python + uv setup
│   ├── setup-node-pnpm/     # Node.js + pnpm setup
│   ├── security-scan/       # Security scanning
│   └── release-notes/       # Changelog generation
├── agents/                  # Autonomous agent definitions (markdown)
├── scripts/                 # Automation scripts
├── profile/                 # Organization profile (github.com/zircote)
└── labels.yml               # Standardized issue/PR labels

Key Patterns

Workflow Security Requirements

All GitHub Actions must use SHA-pinned actions:

# CORRECT - SHA pinned with version comment
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

# WRONG - Never use tag references
- uses: actions/checkout@v4

All workflows must declare minimal permissions:

permissions:
  contents: read  # Minimum required

Reusable Workflow Pattern

Caller workflow (in consuming repository):

jobs:
  ci:
    uses: zircote/.github/.github/workflows/reusable-ci-python.yml@main
    with:
      python-version: '3.12'
      coverage-threshold: 80
    secrets: inherit

Agent Definition Format

Agents use YAML frontmatter in markdown files:

---
name: agent-name
description: Brief description
tools:
  - Read
  - Write
  - Edit
  - Bash
model: sonnet
---

# Agent Name

System prompt and instructions follow...

Skill Definition Format

Skills in .github/skills/*/SKILL.md use:

---
name: skill-name
description: USE THIS SKILL when user says "trigger phrase"
allowed-tools:
  - Bash
  - Read
  - Write
---

# Skill Name

Instructions and patterns...

Available Reusable Workflows

Workflow Purpose Key Inputs
reusable-ci-python.yml Python CI (uv, ruff, pyright, pytest) python-version, coverage-threshold
reusable-ci-typescript.yml TypeScript CI (pnpm, ESLint, Vitest) node-version
reusable-ci-go.yml Go CI (golangci-lint) go-version
reusable-release.yml Semantic release release-type, dry-run
reusable-security.yml Security scanning scan-secrets, scan-dependencies
reusable-docs.yml Documentation deployment framework, deploy-to-pages

Available Composite Actions

Action Purpose
actions/setup-python-uv Install Python + uv with caching
actions/setup-node-pnpm Install Node.js + pnpm with caching
actions/security-scan Run gitleaks + dependency scanning
actions/release-notes Generate changelog from commits

Label Synchronization

Sync standardized labels to a repository:

gh workflow run sync-labels.yml -f repo=zircote/my-repo

Or use github-label-sync directly:

npx github-label-sync --access-token $GITHUB_TOKEN --labels labels.yml zircote/repo-name

Scheduled Workflows (Standard GitHub Actions)

Workflow Schedule Purpose
dependabot-rollout.yml Weekly (Mon 09:30 UTC) Ensure all repos have Dependabot config + automerge
dependabot-sweep.yml Daily (10:00 UTC) Approve + merge open Dependabot PRs with passing CI

gh-aw Agentic Workflows

The following gh-aw agentic workflows are defined in .github/workflows/:

Workflow Tracker ID Schedule Timeout
org-monitor.md orgmon01 daily 15 min
agent-health-monitor.md agenthm01 daily 10 min
stale-health-check.md stlhlt01 weekly 20 min
dependency-ecosystem.md depeco01 weekly 25 min
daily-standup.md dlystd01 daily weekdays 20 min
daily-review-nudge.md dlyrnu01 daily weekdays 20 min
daily-triage.md dlytri01 daily weekdays 20 min
maintenance-board.md mntbrd01 daily 30 min
maintenance-ci.md mntci001 daily 30 min
smart-alerts.md smalrt01 every 6 hours 20 min
housekeeping-branches.md hkbran01 weekly sun 30 min
housekeeping-deps.md hkdeps01 weekly mon 30 min
housekeeping-labels.md hklbls01 weekly mon 30 min
housekeeping-stale.md hkstale1 weekly sun 30 min
maintenance-release.md mntrel01 weekly mon 30 min
smart-retro.md smretro1 every 14 days 30 min
scheduler.md sched001 daily 15 min

Compiling

gh-aw workflows are markdown files that compile to .lock.yml via gh aw compile. The lock file is auto-generated — do not edit it directly.

Known issue: Repos named .github trigger a runtime-import path bug (github/gh-aw#18711). Use the generic patching script instead:

# Compile + patch a single workflow
bash scripts/compile-gh-aw.sh <workflow-name>

# Compile + patch all gh-aw workflows
for wf in org-monitor agent-health-monitor stale-health-check dependency-ecosystem \
          daily-standup daily-review-nudge daily-triage maintenance-board maintenance-ci \
          smart-alerts housekeeping-branches housekeeping-deps housekeeping-labels \
          housekeeping-stale maintenance-release smart-retro scheduler; do
  bash scripts/compile-gh-aw.sh "$wf"
done

# Legacy wrapper (org-monitor only)
bash scripts/compile-org-monitor.sh

gh-aw Frontmatter Rules

  • permissions: block is read-only — write operations go through safe-outputs:
  • Event triggers (issues, pull_request, issue_comment) require reaction: eyes
  • Schedule triggers (schedule: daily) do NOT need reaction: eyes
  • tools.github.app requests ALL workflow-level permissions for the App token — the GitHub App must have every permission in the permissions: block
  • Validate with gh aw compile before committing — it catches trigger errors, permission mismatches, and safe-output violations

GitHub App (zircote-org-monitor)

Cross-repo MCP access uses a GitHub App. Required App permissions must match the workflow's permissions: block exactly. Credentials:

  • GH_APP_ID — repository variable
  • GH_APP_PRIVATE_KEY — repository secret
  • COPILOT_GITHUB_TOKEN — fine-grained PAT with Copilot Requests: Read (account permission, not repo)

Git Conventions

  • Use Conventional Commits: feat:, fix:, docs:, chore:, refactor:, perf:, test:, ci:
  • Keep commits atomic and focused
  • Reference issues in commit messages when applicable

Language Standards (for Templates)

Language Version Package Manager Linter/Formatter Type Checker
Python 3.12+ uv ruff pyright
TypeScript Node 22+ pnpm ESLint 9+ strict tsc
Go 1.23+ modules golangci-lint built-in
Rust stable cargo clippy built-in
Java 21 LTS Gradle Checkstyle -