feat: Add/update AGENTS.md for AI agent guidance

[jaykrishna316]

PR DESCRIPTION FOR: anthropic-sdk-python
AI Readiness: 70/100 (AI-Native-Plus)

Braxis: AI Context Files + Continuous Auto-Update

We've analyzed anthropic-sdk-python 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: 70/100 (AI-Native-Plus)

AI Readiness Score Breakdown

Category	Score	Status
Architecture	0/20	❌ Weak
Testing	15/15	✅ Strong
Dependencies	12/12	✅ Strong
Conventions	10/10	✅ Strong
Entry Points	0/10	❌ Weak
Security	10/15	⚠️ Fair
Build	10/10	✅ Strong
Documentation	8/8	✅ Strong

Total: 70/100 (AI-Native-Plus)

---

We Detected Your Existing Files (Quality Score: 100/100)

You already have valuable custom content in your existing AGENTS.md:

• ✅ Custom AGENTS.md with 5 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:

# .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 for more info
• Check the AI readiness breakdown in the generated AGENTS.md

Generated by Braxis — Keeping AI agents in sync with your code

================================================================================
BRANCH NAME SUGGESTION:
braxis/add-agents-md-$(date +%s)

COMMIT MESSAGE:
feat: Add/update AGENTS.md for AI agent guidance

Generated by Braxis
https://github.com/jaykrishna316/braxis

Co-Authored-By: Jayakrishna Ichapurapu jaykrishna316@gmail.com