.github Repository

This is a special GitHub repository that provides default community health files and templates for all repositories in the scotlaclair organization.

What This Repository Does

Files placed in this repository are automatically applied to all other repositories that don't have their own versions of these files.

Available Workflow Templates

This repository includes several workflow templates that can be used across all repositories in the organization. These templates help automate common maintenance tasks:

Automated Cleanup Workflows

1. Cleanup Old Workflow Runs

File: workflow-templates/cleanup-workflow-runs.yml

Automatically deletes old workflow runs to keep your Actions tab clean and organized.

Settings:

• Runs weekly on Sunday at midnight
• Retains runs for 30 days
• Keeps minimum of 6 runs per workflow
• Can be triggered manually

How to enable:

1. Go to the Actions tab in your repository
2. Click "New workflow"
3. Find "Cleanup Old Workflow Runs" in the template list
4. Click "Configure" and commit the file

2. Cleanup Old Artifacts

File: workflow-templates/cleanup-artifacts.yml

Removes old build artifacts to save storage space.

Settings:

• Runs weekly on Sunday at 2 AM
• Deletes artifacts older than 30 days
• Keeps 5 most recent artifacts
• Can be triggered manually

3. Cleanup Stale Branches

File: workflow-templates/cleanup-stale-branches.yml

Automatically deletes stale branches that haven't been updated recently.

Settings:

• Runs weekly on Sunday at 3 AM
• Deletes branches not updated in 90 days
• Only affects branches with prefixes: feature/, bugfix/, hotfix/, dependabot/
• Protected branches are never deleted
• Defaults to dry run mode (set dry_run: false to enable actual deletions)
• Can be triggered manually

⚠️ Important:

1. The workflow defaults to dry run mode. Review the workflow logs to verify which branches will be deleted before enabling actual deletions.
2. To enable actual deletions, set dry_run: false in the workflow file.
3. Configure automatic branch deletion in your repository settings:
   • Go to Settings → General → Pull Requests
   • Enable "Automatically delete head branches"
   • This ensures merged branches are cleaned up automatically

4. Mark Stale Issues and PRs

File: workflow-templates/stale.yml

Automatically marks and closes stale issues and pull requests.

Settings:

• Runs daily at 1:30 AM
• Marks issues as stale after 60 days of inactivity
• Marks PRs as stale after 60 days of inactivity
• Closes stale items after 7 additional days
• Stale label can be removed by commenting
• Can be triggered manually

5. Lock Old Threads

File: workflow-templates/lock-threads.yml

Locks old closed issues and pull requests to prevent unnecessary comments.

Settings:

• Runs daily at midnight
• Locks issues closed for 365 days
• Locks PRs closed for 365 days
• Can be triggered manually

How to Use Workflow Templates

Method 1: Via GitHub UI

1. Navigate to your repository's Actions tab
2. Click "New workflow"
3. Find the desired workflow template
4. Click "Configure" and customize if needed
5. Commit the workflow file

Method 2: Manual Copy

1. Copy the desired .yml file from the workflow-templates/ directory
2. Create a .github/workflows/ directory in your repository
3. Paste the workflow file and customize as needed
4. Commit and push

Customization

All workflows can be customized by adjusting parameters such as:

• Schedule (cron expressions)
• Retention periods
• Number of items to keep
• Labels and messages
• Branch name patterns

Refer to each workflow's documentation comments for available options.

Recommended Settings

For optimal maintenance automation:

1. Enable automatic branch deletion:

   • Settings → General → Pull Requests → "Automatically delete head branches"

2. Review workflow permissions:

   • Settings → Actions → General → Workflow permissions
   • Ensure workflows have necessary permissions

3. Customize schedules:

   • Adjust cron schedules based on repository activity
   • Stagger workflows to avoid resource contention

AI Review Orchestration System

This repository includes a powerful label-based AI Review Orchestration system that provides deterministic, automated code review across multiple AI agents.

Overview

The AI Review system uses GitHub labels as a state machine to orchestrate code reviews through multiple stages. This approach eliminates fragile natural language parsing and provides clear, auditable state transitions.

Key Features

• 🏷️ Label-Based State Machine: Deterministic state transitions via GitHub labels
• 📊 Structured State Artifacts: Reviews stored as JSON artifacts, not unstructured comments
• 🔄 Multi-Stage Pipeline: 4-stage review process (Gemini → Copilot → Codex → Final)
• 📈 Dashboard: Real-time visibility into review pipeline status
• 🔒 Security-First: Dedicated security analysis stage
• ✅ Auditable: Complete history via label events and artifacts

Review Pipeline Stages

PR Opened
    ↓
🟣 Stage 1: Gemini
    → Initial code analysis and architectural review
    ↓
🔵 Stage 2: Copilot
    → Code quality and best practices
    ↓
🔴 Stage 3: Codex
    → Security vulnerability analysis
    ↓
🟢 Stage 4: Final
    → Final confirmation and summary
    ↓
✅ Complete
    → Ready for human review

Available AI Review Workflows

1. AI Review Orchestrator (Label Based)

File: workflow-templates/ai-review-orchestrator.yml

The main orchestrator that manages the state machine and label transitions.

Features:

• Automatically starts review when PR is opened
• Manages state transitions between stages
• Posts progress updates as comments
• Resets review when PR is updated
• Handles blocked state for human intervention

Triggers:

• PR opened (starts with Stage 1)
• PR labeled (progresses through stages)
• PR synchronized (resets to Stage 1)

How to enable:

1. Go to Actions tab → New workflow
2. Find "AI Review Orchestrator (Label Based)"
3. Click "Configure" and commit

2. AI Review Helper (Label Based)

File: workflow-templates/ai-review-helper.yml

Routes reviews to appropriate AI agents based on labels.

Features:

• Routes to agent based on stage label
• Provides agent-specific context
• Triggers agent workflows
• Logs routing decisions

Agent Mapping:

• ai-review/stage-1-gemini → Gemini Code Assist
• ai-review/stage-2-copilot → Copilot
• ai-review/stage-3-codex → Codex Security
• ai-review/stage-4-final → Copilot Final

3. AI Review Dashboard

File: workflow-templates/ai-review-dashboard.yml

Generates a comprehensive dashboard of all PRs in the review pipeline.

Features:

• Shows PRs by review stage
• Displays age and last update time
• Highlights blocked reviews
• Runs every 6 hours (configurable)

How to enable:

1. Go to Actions tab → New workflow
2. Find "AI Review Dashboard"
3. Click "Configure" and commit

4. Setup AI Review Labels

File: workflow-templates/setup-ai-review-labels.yml

Automatically creates all required labels for the AI review system.

Creates these labels:

• ai-review/needs-triage (🟡 Yellow)
• ai-review/stage-1-gemini (🟣 Purple)
• ai-review/stage-2-copilot (🔵 Blue)
• ai-review/stage-3-codex (🔴 Red)
• ai-review/stage-4-final (🟢 Green)
• ai-review/complete (✅ Bright Green)
• ai-review/blocked (⚠️ Dark Red)
• ai-queue (🟦 Teal)

How to run:

1. Add workflow to .github/workflows/
2. Go to Actions → Setup AI Review Labels
3. Click "Run workflow"
4. Labels will be created automatically

State Artifact Pattern

Instead of leaving unstructured comments, AI agents read from and write to a state.json artifact:

{
  "version": "1.0",
  "pr_number": 123,
  "repository": "owner/repo",
  "current_stage": 2,
  "stages": {
    "1": {
      "agent": "gemini",
      "status": "complete",
      "findings_count": 3,
      "findings": [
        {
          "id": "G001",
          "severity": "warning",
          "category": "security",
          "file": "src/main.py",
          "line": 42,
          "message": "Potential SQL injection vulnerability"
        }
      ]
    }
  }
}

Benefits:

• Deterministic: No parsing of natural language
• Structured: Easy to query and analyze
• Clean: No comment thread pollution
• Auditable: Complete history in artifacts

See profile/ai-review-state-schema.md for full schema documentation.

Quick Start

For Repository Administrators

1. Create labels (one-time setup):

   # Add the label setup workflow
   mkdir -p .github/workflows
   curl -o .github/workflows/setup-ai-review-labels.yml \
     https://raw.githubusercontent.com/scotlaclair/.github/main/workflow-templates/setup-ai-review-labels.yml
   
   # Run it
   gh workflow run setup-ai-review-labels.yml

2. Enable AI Review workflows:

   • Go to Actions → New workflow
   • Add "AI Review Orchestrator (Label Based)"
   • Add "AI Review Helper (Label Based)"
   • Add "AI Review Dashboard" (optional but recommended)

3. Configure permissions:

   • Settings → Actions → General
   • Workflow permissions: "Read and write permissions"
   • Enable "Allow GitHub Actions to create and approve pull requests"

For Contributors

When you open a PR:

1. The ai-review/stage-1-gemini label is added automatically
2. AI review progresses through stages automatically
3. Check labels to see current stage
4. If blocked (ai-review/blocked), address issues in comments
5. When complete (ai-review/complete), request human review

Issue Templates

🤖 AI Feature Request

Optimized template for AI agents to understand and implement features.

Includes:

• Context & Goal (for Copilot)
• Security Constraints (for Gemini)
• Requirements & Acceptance Criteria
• Agent Assignment
• Priority Level

How to use:

1. Go to Issues → New issue
2. Select "🤖 AI Feature Request"
3. Fill in all required fields
4. Submit with ai-queue label

🐛 Bug Report

Standard bug report template.

Documentation

• AI Review Labels: Complete label reference and setup guide
• AI Review State Schema: State artifact format and usage
• Copilot Instructions: Guidelines for AI coding assistants

Design Principles

1. Deterministic over heuristic: Labels are atomic state transitions, not fuzzy text matching
2. Structured data over free text: state.json artifact instead of comment parsing
3. Explicit over implicit: Clear state machine with documented transitions
4. Auditable: All state changes visible in label history and artifacts

Architecture

Pull Request Event
       ↓
Orchestrator Workflow
       ↓
   Add Label (stage-1-gemini)
       ↓
Helper Workflow (detects label)
       ↓
Route to Gemini Agent
       ↓
Agent performs review
       ↓
Agent updates state.json
       ↓
Agent uploads artifact
       ↓
Agent removes stage-1 label
Agent adds stage-2 label
       ↓
[Repeat for stages 2-4]
       ↓
Agent adds "complete" label
       ↓
Human Review

Troubleshooting

Labels not triggering workflows:

• Check workflow permissions in Settings → Actions
• Verify workflows are in .github/workflows/
• Ensure trigger events include labeled

Multiple stage labels active:

• Manually remove all but current stage label
• Review agent logs to identify issue
• Update agent code to properly clean up labels

Blocked state not clearing:

• Review blocking comment for required actions
• Address issues mentioned
• Manually remove ai-review/blocked label
• Review resumes from current stage

Advanced Usage

Skip Stages

To skip a stage, manually change labels:

gh pr edit 123 --remove-label "ai-review/stage-2-copilot" \
                --add-label "ai-review/stage-3-codex"

Restart Review

# Remove all stage labels
gh pr edit 123 --remove-label "ai-review/stage-2-copilot"
# Add stage-1 label
gh pr edit 123 --add-label "ai-review/stage-1-gemini"

Query State Artifacts

# Download state artifact for PR #123
gh run download --name ai-review-state
cat state.json | jq '.stages'

Initial Setup

This repository is being initialized with a complete template system including:

• Automated cleanup workflows (see above)
• AI Review Orchestration workflows (see above)
• Community health files (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY)
• Issue and PR templates (including AI Feature Request)
• Workflow templates for CI/CD