jaykrishna316 opened a new pull request, #52020:
URL: https://github.com/apache/arrow/pull/52020
================================================================================
PR DESCRIPTION FOR: arrow
AI Readiness: 92/100 (Agent-Optimized)
================================================================================
# Braxis: AI Context Files + Continuous Auto-Update
We've analyzed arrow and generated AI-ready context files:
- **AGENTS.md** — AI agent guidance + architecture documentation
- **CLAUDE.md** — Quick reference router to AGENTS.md
- **.cursorrules** — IDE/Claude Code conventions
- **.agentic-config.json** — Agent configuration
**AI Readiness Score:** 92/100 (Agent-Optimized)
### AI Readiness Score Breakdown
| Category | Score | Status |
|----------|-------|--------|
| Architecture | 15/20 | ⚠️ Fair |
| Testing | 15/15 | ✅ Strong |
| Dependencies | 12/12 | ✅ Strong |
| Conventions | 10/10 | ✅ Strong |
| Entry Points | 7/10 | ⚠️ Fair |
| Security | 15/15 | ✅ Strong |
| Build | 10/10 | ✅ Strong |
| Documentation | 8/8 | ✅ Strong |
**Total: 92/100** (Agent-Optimized)
---
## We Detected Your Existing Files (Quality Score: 35/100)
You already have valuable custom content in your existing AGENTS.md:
- ✅ Custom AGENTS.md with 3 sections
We respect this expertise and recommend **keeping it**.
### ⭐ The Real Win: Auto-Update While Preserving Your Work
Even if you choose to keep your existing AGENTS.md now, **installing Braxis
enables continuous auto-updates that respect your custom work**:
- **When:** On significant code changes (src files, architecture,
dependencies) + weekly safety check
- **What happens:** Braxis regenerates all 4 files using `--smart-merge`
(skips trivial changes like docs/comments)
- **Your sections:** Automatically preserved (Skills, Governance, Package
Domains, API Reference, etc.)
- **New content:** Auto-discovered architecture, test frameworks, entry
points stay current
- **How:** Creates a PR for review - you always see the changes before
merging
**This is the real value:** Your custom expertise stays intact, but the
auto-generated parts stay fresh with your code changes.
## What This PR Suggests
We've generated new context files based on current code analysis:
### Recommended Approach
**Option A (Recommended): Keep Your Files + Get Auto-Update Capability**
- ✅ Keep your existing, hand-maintained AGENTS.md
- ✅ Accept our CLAUDE.md + .cursorrules + .agentic-config.json
- ✅ Install Braxis so these files auto-update going forward
> **How Option A Works with Auto-Updates:**
>
> When you install Braxis (via the GitHub Actions workflow), it
intelligently regenerates on significant changes:
> 1. **Detects** significant code changes (source files, architecture,
dependencies)
> 2. **Skips** trivial changes (docs, comments, formatting) to avoid noise
> 3. **Regenerates** context files when it matters using `--smart-merge`
> 4. **Automatically preserves** your custom sections (Skills, Governance,
Architecture notes, etc.)
> 5. **Adds new auto-discovered content** (updated entry points, test
frameworks, etc.)
> 6. Creates a PR for you to review before merging
>
> **Your custom AGENTS.md sections stay yours.** Braxis just keeps the
auto-discovered parts fresh when your code actually changes.
**Option B: Review New Sections**
- Look at our generated AGENTS.md
- Copy any sections you find valuable
- Merge them into your existing file manually
- Install Braxis for auto-updates
**Option C: Accept All Files**
- Use our generated versions
- Customize them after merge
- Install Braxis for auto-updates
## Keep Everything Auto-Updated: Install Braxis
The real value isn't these initial files—it's **keeping your AI context
fresh automatically** as your codebase evolves.
Whether you choose Option A, B, or C, install this GitHub Actions workflow:
```yaml
# .github/workflows/ai-context.yml
name: Auto-Update AI Context Files
on:
push:
branches: [main, master, devel]
schedule:
- cron: '0 0 * * 0' # Weekly fallback
jobs:
detect-changes:
name: Check for Significant Changes
runs-on: ubuntu-latest
outputs:
significant: ${ steps.check.outputs.significant }
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Detect Significant Changes
id: check
run: |
python3 -c "
import subprocess, os
files = subprocess.run(['git', 'diff', '--name-only',
'origin/main...HEAD'],
capture_output=True, text=True).stdout.split()
# Source code changes = regenerate
src_changes = any(f.endswith(('.py', '.js', '.ts', '.java',
'.go')) for f in files)
build_changes = any('package.json' in f or 'setup.py' in f for f
in files)
struct_changes = any('src/' in f or 'lib/' in f or 'packages/' in
f for f in files)
significant = src_changes or build_changes or struct_changes
with open(os.environ['GITHUB_OUTPUT'], 'a') as f:
f.write('significant=' + str(significant).lower())
"
update-context:
name: Update AI Context Files
runs-on: ubuntu-latest
needs: detect-changes
if: needs.detect-changes.outputs.significant == 'true' ||
github.event_name == 'schedule'
steps:
- uses: actions/checkout@v3
- run: pip install braxis
- run: braxis generate --smart-merge --path .
- uses: peter-evans/create-pull-request@v5
with:
commit-message: 'chore: auto-update AI context files'
title: 'Auto: Update AI context files'
branch: braxis/auto-update
```
**Why this matters:**
- Detects significant code changes (source files, architecture, dependencies)
- Skips regeneration for trivial changes (docs, comments, formatting)
- Regenerates on every code push (when it matters) + weekly safety check
- Uses `--smart-merge` to preserve your hand-written sections
- Creates PRs for you to review and merge
- Keeps AI readiness score current without noise
- **Zero manual maintenance, minimal PR spam**
### 💡 Even If You Reject This PR
Choosing not to merge this PR? **Installing Braxis still helps:**
- ✅ Your existing AGENTS.md stays unchanged
- ✅ Braxis auto-detects your custom file using smart-merge
- ✅ Weekly auto-updates keep your context fresh (no noise, only significant
changes)
- ✅ Your hand-written sections are always preserved
- ✅ New auto-discovered content integrates smoothly
**The decision is yours on the files, but the workflow benefit is always
available.**
Even repo owners who prefer their own AGENTS.md can benefit from continuous
updates that respect their choices.
## Next Steps
1. **Choose your option** (A, B, or C above)
2. **Merge this PR** with your choice (or decline it)
3. **Install the workflow** for automatic updates
4. Your AI context stays fresh going forward
**Note:** Installing the Braxis workflow works whether you merge this PR or
not.
---
## Summary: The Value Braxis Provides
**Immediate:** Fresh AI context files (or validation of your existing ones)
**Ongoing:** Automatic updates keep context in sync with code changes
### To Keep Your AI Context Files Up-to-Date
✅ **Install Braxis** (add the GitHub Actions workflow above)
This ensures:
- Your AGENTS.md, CLAUDE.md, .cursorrules, and .agentic-config.json stay
current
- AI agents always have accurate project information
- No manual updates needed - Braxis handles it automatically
- AI readiness score tracked over time
---
**Questions?**
- See [Braxis docs](https://github.com/jaykrishna316/braxis) for more info
- Check the AI readiness breakdown in the generated AGENTS.md
**Generated by [Braxis](https://github.com/jaykrishna316/braxis)** — Keeping
AI agents in sync with your code
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
