This repository contains organization-wide GitHub configuration, reusable workflows, and Claude Code Action integration for all HappyVertical repositories.
The HappyVertical organization uses Claude Code Action for automated:
- Issue triage - Categorize, prioritize, and size new issues
- Issue checkup - Scheduled hygiene scan to catch issues needing attention
- @claude mentions - AI assistance in issues and PRs
- CI failure auto-fix - Automatically fix failing CI builds
- Test failure analysis - Analyze and detect flaky tests
- Agent autopilot - Full implementation automation via
dispatch: claude; active ownership remainsagent: implementation
Copy the workflow templates from .github/workflow-templates/ to your repository's .github/workflows/ directory:
# From your repository root
cp ../../../.github/.github/workflow-templates/*.yml .github/workflows/Or create them manually - see the templates for the required configuration.
In your repository settings (Settings → Secrets and variables → Actions → Variables), add:
| Variable | Description | Example |
|---|---|---|
REPO_DESCRIPTION |
Brief repo description | "Core SDK packages" |
PACKAGE_PATTERN |
Package naming pattern | @happyvertical/* |
PROJECT_ID |
GitHub Projects board ID | PVT_kwDOB9Y8ns4A8-TY |
STATUS_FIELD_ID |
Status field ID | PVTSSF_... |
STATUS_*_ID |
Status option IDs | See your project settings |
AGENT_POLICY_ARTIFACT |
Signed public policy OCI digest | ghcr.io/.../agent-policy@sha256:... |
The organization-level CI_LINUX_RUNNER variable selects the general Linux CI
pool for centrally managed reusable workflows. It defaults to
arc-happyvertical when unset. Repository-owned workflows should use the same
expression for general jobs:
runs-on: ${{ vars.CI_LINUX_RUNNER || 'arc-happyvertical' }}Keep specialized selectors such as deployment, macOS, and dedicated database runners explicit rather than routing them through this variable.
The following secrets should be configured at the org level:
| Secret | Description |
|---|---|
CLAUDE_CODE_OAUTH_TOKEN |
Claude Code Max OAuth token |
Automatically triages new issues:
- Assigns type label (bug, feature, docs, maintenance, research, question)
- Assigns priority label (critical, high, medium, low, icebox)
- Assigns size label (xs, s, m, l, xl)
- Checks for duplicate issues
- Adds to project board
Caller example:
name: Issue Opened
on:
issues:
types: [opened]
jobs:
triage:
uses: happyvertical/.github/.github/workflows/org-issue-triage.yml@main
with:
issue_number: ${{ github.event.issue.number }}
issue_title: ${{ github.event.issue.title }}
issue_body: ${{ github.event.issue.body || '' }}
issue_author: ${{ github.event.issue.user.login }}
secrets:
CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}Responds to @claude mentions in:
- Issue comments
- PR comments
- PR reviews
- Issue body/title
Claude can read code, make changes, create PRs, and more.
Triggered when CI workflows fail:
- Analyzes failure logs
- Attempts automatic fix
- Commits and pushes if successful
- Comments on PR if unable to fix
Analyzes test failures:
- Identifies root causes
- Detects flaky tests
- Provides actionable recommendations
- Posts analysis as PR comment
Full autonomous implementation triggered by dispatch: claude:
- Reads the issue and CLAUDE.md
- Creates feature branch
- Implements the solution
- Runs quality checks
- Creates pull request
If Claude is blocked (unclear requirements, needs decisions), it posts a comment asking for clarification and removes the label. Re-apply the label once clarified.
This workflow requires AGENT_POLICY_ARTIFACT to be set and a GH_TOKEN secret
carrying org Projects v2 scope. It exits non-zero without the former, and its
claim/heartbeat/release steps cannot write project state with the default
GITHUB_TOKEN. See .github/workflow-templates/claude-autopilot.yml.
Because it is reachable only through workflow_call, org-agent-autopilot-smoke.yml
invokes it against a closed issue so the call contract, input and secret
binding, and runner dispatch are exercised on every pull request that touches
either file. The closed-issue target makes the autopilot short-circuit at its
first step, so the smoke test never starts agent work; a preflight guard job
refuses to call the autopilot unless the target really is closed. It passes
GITHUB_TOKEN rather than the org GH_TOKEN, because a local uses: runs the
pull request's own copy of the reusable workflow. Run it by hand with
gh workflow run org-agent-autopilot-smoke.yml.
Scheduled hygiene workflow to catch issues that slipped through triage:
- Runs weekly (configurable) or on-demand via manual trigger
- Scans all open issues for missing labels or incomplete descriptions
- Adds
needs-infolabel to issues requiring human input - Claude comments with specific asks to move issues forward
- Non-destructive: never implements, only triages and flags
Caller example:
name: Issue Checkup
on:
schedule:
- cron: '0 9 * * 1' # Weekly on Mondays
workflow_dispatch:
inputs:
max_issues:
description: 'Maximum issues to process'
default: '20'
jobs:
checkup:
uses: happyvertical/.github/.github/workflows/org-issue-checkup.yml@main
with:
max_issues: ${{ github.event.inputs.max_issues && fromJSON(github.event.inputs.max_issues) || 20 }}
stale_days: 7
secrets:
CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}The .claude/commands/ directory contains prompts for Claude:
| Command | Description |
|---|---|
label-issue.md |
Issue triage prompt |
fix-ci.md |
CI failure fix prompt |
implement-issue.md |
Full implementation prompt |
analyze-tests.md |
Test failure analysis prompt |
type: bug- Something isn't workingtype: feature- New feature or enhancementtype: docs- Documentation improvementstype: maintenance- Maintenance and refactoringtype: research- Research and investigationtype: question- Question or discussion
priority: critical- Immediate attention requiredpriority: high- High prioritypriority: medium- Normal priority (default)priority: low- Low prioritypriority: icebox- Future consideration
size: xs- < 2 hourssize: s- 2-4 hourssize: m- ~1 daysize: l- 2-3 dayssize: xl- > 3 days
dispatch: claude- Triggers Claude implementation automationagent: triage- AI triage in progressagent: planning- AI planning in progressagent: implementation- Sole exclusive implementation ownership signalagent: testing- AI testing in progressagent: review- AI code review in progress
needs-info- Issue needs more information before it can be worked on
The workflows integrate with GitHub Projects:
| Status | Trigger |
|---|---|
| New | Issue opened |
| Backlog | Triage complete |
| Planning | Manual move |
| Ready | Definition of Ready met |
| In Progress | active hv-agent-claim:v1 lease or manual |
| Review | PR created |
| Done | PR merged or issue closed |
To get your project board IDs:
# Get project ID
gh api graphql -f query='
query($org: String!) {
organization(login: $org) {
projectsV2(first: 10) {
nodes {
id
title
}
}
}
}
' -f org="happyvertical"
# Get status field and option IDs
gh api graphql -f query='
query($id: ID!) {
node(id: $id) {
... on ProjectV2 {
fields(first: 20) {
nodes {
... on ProjectV2SingleSelectField {
id
name
options {
id
name
}
}
}
}
}
}
}
' -f id="PVT_xxx"General Linux jobs use the runner selected by the organization-level
CI_LINUX_RUNNER variable, with arc-happyvertical as the fallback. JIT
runners register [self-hosted, Linux, X64, arc-happyvertical], so the
fallback names a label that is actually registered and the workflows resolve
whether or not the variable is set. Specialized workflows retain their
dedicated selectors.
Lifecycle-protected pull requests merge through the managed merge queue so the
synthetic merge revision is revalidated before it reaches main.
When updating workflows:
- Test changes in a single repository first
- Update workflow templates
- Update this README
- Roll out to other repositories