aieng-bot 0.5.0

Vector Institute AI Engineering Bot for Maintenance Tasks

aieng-bot

---

Centralized maintenance bot that automatically manages bot PRs (Dependabot and pre-commit-ci) across all Vector Institute repositories from a single location.

Features

• Organization-wide monitoring - Scans all VectorInstitute repos every 6 hours
• Auto-merge - Merges bot PRs (Dependabot and pre-commit-ci) when all checks pass
• Auto-fix - Fixes test failures, linting issues, security vulnerabilities, and build errors using Claude AI Agent SDK
• Centralized operation - No installation needed in individual repositories
• Smart detection - Categorizes failures and applies appropriate fix strategies
• Transparent - Comments on PRs with status updates

Architecture

┌─────────────────────────────────┐
│  aieng-bot Repository  │
│  (This Repo - Central Bot)      │
│                                 │
│  Runs every 6 hours:            │
│  1. Scans VectorInstitute org   │
│  2. Finds bot PRs               │
│  3. Checks status               │
│  4. Merges or fixes PRs         │
└──────────────┬──────────────────┘
               │
               │ Operates on
               ▼
┌───────────────────────────────────┐
│   VectorInstitute Organization    │
│                                   │
│  ├─ repo-1  (Bot PR #1)           │
│  ├─ repo-2  (Bot PR #2)           │
│  ├─ repo-3  (Bot PR #3)           │
│  └─ repo-N  ...                   │
└───────────────────────────────────┘

Quick Start

Setup (in this repository)

1. Create Anthropic API Key

• Get from Anthropic Console
• Add as repository secret: ANTHROPIC_API_KEY

2. Create GitHub Personal Access Token

• Go to Settings → Developer settings → Personal access tokens → Fine-grained tokens
• Configure: Resource owner: VectorInstitute, Repository access: All repositories
• Permissions: contents: write, pull_requests: write, issues: write
• Add as repository secret: ORG_ACCESS_TOKEN

3. Enable GitHub Actions

• Go to Actions tab → Enable workflows

The bot now monitors all VectorInstitute repositories automatically.

How It Works

1. Monitor (every 6 hours)

• Scans all VectorInstitute repositories for open bot PRs (Dependabot and pre-commit-ci)
• Checks status of each PR
• Routes to merge or fix workflow

2. Auto-Merge (when all checks pass)

• Approves PR and enables auto-merge
• Comments with status
• PR merges automatically

3. Auto-Fix (when checks fail)

• Clones target repository and PR branch
• Analyzes failure type: test, lint, security, or build
• Loads appropriate AI prompt template
• Uses Claude Agent SDK to automatically apply fixes
• Commits and pushes fixes to PR

Configuration

Required Secrets

• ANTHROPIC_API_KEY - Anthropic API access for Claude
• ORG_ACCESS_TOKEN - GitHub PAT with org-wide permissions

Workflows

• monitor-org-bot-prs.yml - Scans org for bot PRs (Dependabot and pre-commit-ci) every 6 hours
• fix-remote-pr.yml - Fixes failing PRs using AI

AI Prompt Templates (customize for your needs)

• fix-merge-conflicts.md - Resolve merge conflicts with best practices
• fix-test-failures.md - Test failure resolution strategies
• fix-lint-failures.md - Linting/formatting fixes
• fix-security-audit.md - Security vulnerability handling
• fix-build-failures.md - Build/compilation error fixes

Capabilities

Can fix:

• Merge conflicts (dependency files, lock files, code)
• Linting and formatting issues
• Security vulnerabilities (dependency updates)
• Simple test failures from API changes
• Build configuration issues

Cannot fix:

• Complex logic errors
• Breaking changes requiring refactoring
• Issues requiring architectural decisions

Manual Testing

Trigger via CLI:

# Monitor all repositories
gh workflow run monitor-org-bot-prs.yml

# Fix a specific PR (test with aieng-template-mvp#17)
gh workflow run fix-remote-pr.yml \
  --field target_repo="VectorInstitute/aieng-template-mvp" \
  --field pr_number="17"

Trigger via GitHub UI: Actions → Select workflow → Run workflow → Enter parameters

Dashboard

View comprehensive analytics and agent execution traces:

• 📊 Bot Dashboard - Interactive dashboard with:
  • Overview table of all bot PR fixes
  • Success rates and performance metrics
  • Detailed agent execution traces (like LangSmith/Langfuse)
  • Code diffs with syntax highlighting
  • Failure analysis and reasoning timeline

Features:

• Real-time PR status tracking
• Agent observability (tool calls, reasoning, actions)
• Historical metrics and trends
• Per-repo and per-failure-type analytics
• Sortable/filterable PR table

Authentication:

• Restricted to @vectorinstitute.ai email addresses
• Google OAuth 2.0 sign-in

Monitoring

View bot activity:

• Dashboard - Comprehensive analytics and traces
• Actions tab - All workflow runs and success/failure rates
• PR comments - Detailed status updates on each PR
• Run summary - PR count and actions taken per run

Debug commands:

# View recent workflow runs
gh run list --workflow=monitor-org-bot-prs.yml --limit 5

# View logs for specific run
gh run view RUN_ID --log

# Collect metrics manually
gh workflow run aieng-bot metrics.yml

Documentation

• Setup Guide - Detailed configuration and permissions
• Deployment Guide - Rollout strategy and monitoring
• Testing Guide - Test cases and validation

Troubleshooting

Issue	Solution
Workflow doesn't run	Check Actions enabled and secrets are set
Can't find PRs	Verify ORG_ACCESS_TOKEN has correct permissions
Can't merge PRs	Ensure token has contents: write permission
Can't push fixes	Check token has write access to target repos
Claude API errors	Verify ANTHROPIC_API_KEY is valid
Rate limits	Reduce monitoring frequency in workflow cron schedule

See Setup Guide for detailed troubleshooting.

---

🤖 AI Engineering Maintenance Bot - Maintaining Vector Institute Repositories built by AI Engineering