braxis 1.0.0__tar.gz

braxis-1.0.0/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+Copyright (c) 2026 Jayakrishna Ichapurapu
+Permission is hereby granted to use this software.

braxis-1.0.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: braxis
+Version: 1.0.0
+Summary: Auto-generate context files for AI agents
+Author: Jayakrishna Ichapurapu
+License: MIT
+Requires-Python: >=3.8
+License-File: LICENSE
+Dynamic: author
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary

braxis-1.0.0/README.md

@@ -0,0 +1,185 @@
+# Braxis
+
+**Auto-generate AI agent context files. Keep them in sync with your code.**
+
+Your AI agents (Claude Code, Cursor, Copilot) read from `AGENTS.md` to understand your project. When your code changes, that file gets stale. Agents miss patterns, violate conventions, hallucinate.
+
+Braxis solves this: **one command generates four context files that stay in sync with your codebase.**
+
+---
+
+## See It In Action
+
+Before Braxis:
+
+Day 1: Agent reads stale AGENTS.md from 2 weeks ago
+Sees old directory structure
+Doesn't know about new error handling pattern
+Makes bad suggestions based on outdated info
+
+
+After Braxis:
+
+Every push: GitHub Actions runs Braxis
+Analyzes current codebase
+Regenerates AGENTS.md, CLAUDE.md, .cursorrules, .agentic-config.json
+Creates PR with updates
+Your agents always see current reality
+
+
+---
+
+## How To Use Braxis On Your Project (5 minutes)
+
+### Step 1: Install
+
+```bash
+pip install braxis
+```
+
+### Step 2: Go to Your Project
+
+```bash
+cd /path/to/your/project
+```
+
+### Step 3: Generate Context Files
+
+```bash
+braxis generate
+```
+
+That's it. Braxis creates:
+
+your-project/
+├── AGENTS.md (Universal agent instructions)
+├── CLAUDE.md (Claude Code optimized)
+├── .cursorrules (Cursor IDE rules)
+├── .agentic-config.json (Machine-readable metadata)
+└── (your existing files)
+
+
+### Step 4: See What It Generated
+
+```bash
+cat AGENTS.md
+```
+
+### Step 5: Commit to Your Repo
+
+```bash
+git add AGENTS.md CLAUDE.md .cursorrules .agentic-config.json
+git commit -m "chore: add AI agent context files"
+git push
+```
+
+### Step 6: Your Agents Now Use These Files
+
+**In Claude Code:** Automatically reads `CLAUDE.md`
+**In Cursor:** Copy `.cursorrules` into Cursor Settings → Rules
+**In any agent:** Reads `AGENTS.md` (universal format)
+
+---
+
+## Make It Auto-Update (Optional)
+
+Create `.github/workflows/braxis.yml`:
+
+```yaml
+name: Auto-Regenerate Context Files
+
+on:
+  push:
+    paths:
+      - 'src/**'
+      - 'lib/**'
+      - 'package.json'
+      - 'pyproject.toml'
+      - 'setup.py'
+
+jobs:
+  regenerate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - run: pip install braxis
+      - run: braxis generate
+      - uses: peter-evans/create-pull-request@v5
+        with:
+          commit-message: "chore: regenerate context files"
+          title: "chore: update AGENTS.md and context files"
+          branch: braxis/auto-update
+```
+
+Now every time you push code, GitHub Actions automatically regenerates all context files.
+
+---
+
+## Customize For Your Project (Optional)
+
+Create `.agentic-config.json`:
+
+```json
+{
+  "name": "MyApp",
+  "description": "A production API service",
+  "exclude_patterns": [
+    "node_modules/**",
+    ".venv/**",
+    "build/**"
+  ],
+  "custom_conventions": {
+    "error_handling": "Always use try/except and log",
+    "async_patterns": "All I/O must be async",
+    "validation": "Use Pydantic models for inputs"
+  },
+  "critical_files": [
+    "src/main.py",
+    "src/api/routes.py",
+    "README.md"
+  ]
+}
+```
+
+---
+
+## What Each File Does
+
+**AGENTS.md** - Universal format read by any AI agent
+
+**CLAUDE.md** - Optimized for Claude Code
+
+**.cursorrules** - Rules for Cursor IDE
+
+**.agentic-config.json** - Machine-readable metadata
+
+---
+
+## Commands
+
+```bash
+braxis generate     # Generate context files
+braxis score        # Score agent readiness (0-100)
+braxis inspect      # See what Braxis found
+braxis validate     # Verify AGENTS.md exists
+```
+
+---
+
+## Requirements
+
+- Python 3.8+
+- Zero external dependencies
+
+---
+
+## License
+
+MIT
+
+---
+
+**Braxis** — Keep your agents aligned. Keep your code context current.

braxis-1.0.0/braxis.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: braxis
+Version: 1.0.0
+Summary: Auto-generate context files for AI agents
+Author: Jayakrishna Ichapurapu
+License: MIT
+Requires-Python: >=3.8
+License-File: LICENSE
+Dynamic: author
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary

braxis-1.0.0/braxis.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+braxis.py
+setup.py
+braxis.egg-info/PKG-INFO
+braxis.egg-info/SOURCES.txt
+braxis.egg-info/dependency_links.txt
+braxis.egg-info/top_level.txt
+tests/test_braxis.py

braxis-1.0.0/braxis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

braxis-1.0.0/braxis.egg-info/top_level.txt

@@ -0,0 +1 @@
+braxis

braxis-1.0.0/braxis.py

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+"""
+Braxis - Auto-generate AI agent context files.
+Keep AGENTS.md, CLAUDE.md, .cursorrules, and .agentic-config.json in sync with your codebase.
+"""
+import os
+import sys
+import json
+import argparse
+import tempfile
+from pathlib import Path
+from collections import defaultdict
+from datetime import datetime
+
+
+class BraxisAnalyzer:
+    """Analyzes a codebase and generates agent context files."""
+
+    LANGUAGE_EXTENSIONS = {
+        'python': ['.py'],
+        'javascript': ['.js', '.jsx'],
+        'typescript': ['.ts', '.tsx'],
+        'java': ['.java'],
+        'go': ['.go'],
+        'rust': ['.rs'],
+        'c': ['.c', '.h'],
+        'cpp': ['.cpp', '.cc', '.cxx', '.h', '.hpp'],
+        'csharp': ['.cs'],
+        'php': ['.php'],
+        'ruby': ['.rb'],
+        'swift': ['.swift'],
+        'kotlin': ['.kt'],
+        'scala': ['.scala'],
+        'r': ['.R', '.r'],
+        'sql': ['.sql'],
+    }
+    TEST_PATTERNS = ['test_', '_test.', 'spec_', '.spec.', 'tests/', 'test/']
+    BUILD_FILES = ['package.json', 'pyproject.toml', 'setup.py', 'Makefile', 'build.gradle', 'pom.xml', 'Cargo.toml']
+    CONFIG_FILES = ['.env', '.env.example', 'config.json', 'settings.py', 'config.yaml']
+
+    def __init__(self, project_path='.'):
+        self.project_path = self._validate_project_path(project_path)
+        self.files = []
+        self.languages = defaultdict(int)
+        self.test_files = []
+        self.config_files = []
+        self.build_files = []
+        self.conventions = defaultdict(int)
+        self.critical_files = []
+        self.score_breakdown = {}
+        self.tier = "Not Ready"
+
+    def _validate_project_path(self, project_path):
+        """Validate and normalize project path."""
+        if not project_path:
+            raise ValueError("Project path cannot be empty")
+        path = Path(project_path).resolve()
+        if not path.exists():
+            raise FileNotFoundError(f"Project path does not exist: {project_path}")
+        if not path.is_dir():
+            raise NotADirectoryError(f"Project path is not a directory: {project_path}")
+        return path
+
+    def analyze(self):
+        """Analyze the project."""
+        self._scan_files()
+        self._detect_languages()
+        self._detect_build_system()
+        self._detect_test_framework()
+        self._detect_conventions()
+        self._identify_critical_files()
+        self._calculate_score()
+
+    def _scan_files(self):
+        """Scan all files in project."""
+        ignore_dirs = {'.git', '.venv', 'node_modules', '__pycache__', 'dist', 'build', '.idea', '.vscode'}
+        for root, dirs, files in os.walk(self.project_path):
+            dirs[:] = [d for d in dirs if d not in ignore_dirs]
+            for file in files:
+                file_path = Path(root) / file
+                self.files.append(file_path)
+                if any(pattern in str(file_path) for pattern in self.TEST_PATTERNS):
+                    self.test_files.append(file_path)
+                if file in self.CONFIG_FILES:
+                    self.config_files.append(file_path)
+                if file in self.BUILD_FILES:
+                    self.build_files.append(file_path)
+
+    def _detect_languages(self):
+        """Detect languages used in project."""
+        for file_path in self.files:
+            ext = file_path.suffix.lower()
+            for lang, exts in self.LANGUAGE_EXTENSIONS.items():
+                if ext in exts:
+                    self.languages[lang] += 1
+                    break
+
+    def _detect_build_system(self):
+        """Detect build system."""
+        build_system = "Unknown"
+        if any('package.json' in str(f) for f in self.build_files):
+            build_system = "npm/Node.js"
+        elif any('pyproject.toml' in str(f) or 'setup.py' in str(f) for f in self.build_files):
+            build_system = "Python (pip/setuptools)"
+        elif any('Cargo.toml' in str(f) for f in self.build_files):
+            build_system = "Rust (cargo)"
+        elif any('go.mod' in str(f) for f in self.build_files):
+            build_system = "Go (go modules)"
+        elif any('pom.xml' in str(f) for f in self.build_files):
+            build_system = "Java (Maven)"
+        self.build_system = build_system
+
+    def _detect_test_framework(self):
+        """Detect test framework."""
+        test_frameworks = set()
+        content_samples = self._sample_file_contents(limit=20)
+        for content in content_samples:
+            if 'pytest' in content or 'from pytest' in content:
+                test_frameworks.add('pytest')
+            if 'unittest' in content or 'import unittest' in content:
+                test_frameworks.add('unittest')
+            if 'jest' in content or 'describe(' in content:
+                test_frameworks.add('Jest')
+            if 'mocha' in content or 'describe(' in content:
+                test_frameworks.add('Mocha')
+            if 'rspec' in content or 'describe' in content:
+                test_frameworks.add('RSpec')
+            if 'junit' in content.lower():
+                test_frameworks.add('JUnit')
+        self.test_frameworks = test_frameworks if test_frameworks else {"None detected"}
+
+    def _detect_conventions(self):
+        """Detect code conventions."""
+        content_samples = self._sample_file_contents(limit=20)
+        for content in content_samples:
+            if 'async def' in content or 'await ' in content:
+                self.conventions['async'] += 1
+            if 'async function' in content or 'async (' in content:
+                self.conventions['async'] += 1
+            if 'try:' in content or 'except' in content:
+                self.conventions['error_handling'] += 1
+            if 'try {' in content or 'catch' in content:
+                self.conventions['error_handling'] += 1
+            if '->' in content or ': ' in content:
+                self.conventions['type_hints'] += 1
+            if 'interface ' in content or 'type ' in content:
+                self.conventions['type_hints'] += 1
+            if 'logger' in content or 'logging' in content:
+                self.conventions['logging'] += 1
+            if 'log.' in content or 'console.log' in content:
+                self.conventions['logging'] += 1
+            if 'validate' in content.lower() or 'schema' in content.lower():
+                self.conventions['validation'] += 1
+
+    def _identify_critical_files(self):
+        """Identify critical files (main, entry points, etc)."""
+        critical_names = ['main.py', 'app.py', 'server.py', 'index.js', 'main.js', 'app.js', 'main.rs', 'main.go', 'main.ts']
+        for file_path in self.files:
+            if file_path.name in critical_names or 'src/main' in str(file_path):
+                self.critical_files.append(file_path)
+
+    def _sample_file_contents(self, limit=20):
+        """Sample file contents for convention detection."""
+        samples = []
+        code_files = [f for f in self.files if f.suffix in ['.py', '.js', '.ts', '.go', '.rs', '.java']]
+        for file_path in code_files[:limit]:
+            try:
+                with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+                    samples.append(f.read())
+            except Exception:
+                pass
+        return samples
+
+    def _calculate_score(self):
+        """Calculate agent readiness score."""
+        scores = {}
+        arch_score = min(20, len(self.critical_files) * 5 + 10)
+        scores['Architecture'] = arch_score
+        test_score = min(15, len(self.test_files) * 2 + 5)
+        scores['Testing'] = test_score
+        dep_score = 12 if self.build_system != "Unknown" else 6
+        scores['Dependencies'] = dep_score
+        convention_count = sum(1 for v in self.conventions.values() if v > 0)
+        conv_score = min(10, convention_count * 2)
+        scores['Conventions'] = conv_score
+        entry_score = min(10, len(self.critical_files) * 3 + 4)
+        scores['Entry Points'] = entry_score
+        sec_score = 10 if 'validation' in self.conventions else 5
+        sec_score += 5 if len(self.config_files) > 0 else 0
+        scores['Security'] = min(15, sec_score)
+        build_score = 10 if len(self.build_files) > 0 else 5
+        scores['Build'] = build_score
+        readme_exists = any(f.name.lower() == 'readme.md' for f in self.files)
+        doc_score = 8 if readme_exists else 3
+        scores['Documentation'] = doc_score
+        self.score_breakdown = scores
+        total_score = sum(scores.values())
+        self.total_score = total_score
+        if total_score >= 90:
+            self.tier = "Agent-Optimized"
+        elif total_score >= 80:
+            self.tier = "AI-Native-Plus"
+        elif total_score >= 60:
+            self.tier = "AI-Native"
+        elif total_score >= 30:
+            self.tier = "Agent-Aware"
+        else:
+            self.tier = "Not Ready"
+
+    def _write_file_safely(self, filepath, content):
+        """Write file safely using atomic operation with temp file."""
+        if not filepath:
+            raise ValueError("Filepath cannot be empty")
+        if not isinstance(content, str):
+            raise TypeError(f"Content must be str, got {type(content).__name__}")
+        filepath = Path(filepath)
+        tmp_path = None
+        try:
+            filepath.parent.mkdir(parents=True, exist_ok=True)
+            with tempfile.NamedTemporaryFile(
+                mode='w',
+                dir=filepath.parent,
+                suffix='.tmp',
+                delete=False,
+                encoding='utf-8'
+            ) as tmp_file:
+                tmp_file.write(content)
+                tmp_path = Path(tmp_file.name)
+            tmp_path.replace(filepath)
+        except Exception as e:
+            if tmp_path and tmp_path.exists():
+                tmp_path.unlink()
+            raise IOError(f"Failed to write file {filepath}: {e}")
+
+    def print_score(self):
+        """Print the score report."""
+        print(f"\n{'='*60}")
+        print(f"Agent Readiness Score: {self.total_score}/100")
+        print(f"{'='*60}\n")
+        print("Breakdown:\n")
+        for category, score in self.score_breakdown.items():
+            bar = chr(9608) * (score // 5) + chr(9617) * ((100 - score) // 5)
+            print(f" {category:20} {score:3}/100 [{bar}]")
+        print(f"\nTier: {self.tier}")
+        print(f"\nDetected:")
+        print(f" Languages: {', '.join(self.languages.keys()) if self.languages else 'None'}")
+        print(f" Build System: {self.build_system}")
+        print(f" Test Frameworks: {', '.join(self.test_frameworks)}")
+        print(f" Test Files: {len(self.test_files)}")
+        print(f" Critical Files: {len(self.critical_files)}")
+        print(f"\nRecommendations:")
+        if self.score_breakdown['Documentation'] < 8:
+            print(f" * Add or improve README.md")
+        if self.score_breakdown['Testing'] < 15:
+            print(f" * Increase test coverage")
+        if self.score_breakdown['Conventions'] < 10:
+            print(f" * Standardize code conventions")
+        if self.score_breakdown['Security'] < 15:
+            print(f" * Add input validation and security checks")
+        print(f"\nNext Step:")
+        print(f" braxis generate")
+        print(f"\n{'='*60}\n")
+
+    def generate_agents_md(self):
+        """Generate AGENTS.md file."""
+        primary_lang = max(self.languages.items(), key=lambda x: x[1])[0] if self.languages else "Unknown"
+        content = f"""# AGENTS.md
+AI agents read this file to understand your project.
+## Project Identity
+This is a {primary_lang.capitalize()} project. It uses {self.build_system}.
+## Tech Stack
+- Language: {primary_lang.capitalize()}
+- Build: {self.build_system}
+- Testing: {', '.join(self.test_frameworks)}
+- Total Files: {len(self.files)}
+## Quick Start
+"""
+        return content
+
+    def generate_claude_md(self):
+        """Generate CLAUDE.md file."""
+        primary_lang = max(self.languages.items(), key=lambda x: x[1])[0] if self.languages else "Unknown"
+        content = f"""# CLAUDE.md
+Quick context for Claude Code working in this project.
+## Project
+{primary_lang.capitalize()} project using {self.build_system}.
+"""
+        return content
+
+    def generate_cursorrules(self):
+        """Generate .cursorrules file."""
+        primary_lang = max(self.languages.items(), key=lambda x: x[1])[0] if self.languages else "Unknown"
+        rules = f"""# Cursor Rules
+This is a {primary_lang.capitalize()} project using {self.build_system}.
+"""
+        return rules
+
+    def generate_agentic_config(self):
+        """Generate .agentic-config.json file."""
+        primary_lang = max(self.languages.items(), key=lambda x: x[1])[0] if self.languages else "Unknown"
+        config = {
+            "name": self.project_path.name,
+            "description": f"A {primary_lang.capitalize()} project",
+            "language": primary_lang,
+            "build_system": self.build_system,
+            "agent_readiness_score": self.total_score,
+            "tier": self.tier,
+        }
+        return json.dumps(config, indent=2)
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Braxis - AI agent context generator')
+    parser.add_argument('command', choices=['generate', 'score', 'inspect', 'validate'],
+                        help='Command to run')
+    parser.add_argument('--path', default='.', help='Project path')
+    args = parser.parse_args()
+
+    if not args.command or args.command not in ['generate', 'score', 'inspect', 'validate']:
+        parser.print_help()
+        sys.exit(1)
+
+    try:
+        analyzer = BraxisAnalyzer(args.path)
+        analyzer.analyze()
+    except (ValueError, FileNotFoundError, NotADirectoryError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.command == 'score':
+        analyzer.print_score()
+    elif args.command == 'generate':
+        print("Generating context files...")
+        try:
+            analyzer._write_file_safely('AGENTS.md', analyzer.generate_agents_md())
+            print("* AGENTS.md")
+            analyzer._write_file_safely('CLAUDE.md', analyzer.generate_claude_md())
+            print("* CLAUDE.md")
+            analyzer._write_file_safely('.cursorrules', analyzer.generate_cursorrules())
+            print("* .cursorrules")
+            analyzer._write_file_safely('.agentic-config.json', analyzer.generate_agentic_config())
+            print("* .agentic-config.json")
+            print(f"\nAgent Readiness: {analyzer.total_score}/100 ({analyzer.tier})")
+            print("\nFiles created successfully!")
+        except IOError as e:
+            print(f"Error writing files: {e}", file=sys.stderr)
+            sys.exit(1)
+    elif args.command == 'inspect':
+        print(f"\nProject Analysis:")
+        print(f" Languages: {dict(analyzer.languages)}")
+        print(f" Build System: {analyzer.build_system}")
+        print(f" Test Frameworks: {list(analyzer.test_frameworks)}")
+        print(f" Files: {len(analyzer.files)}")
+        print(f" Test Files: {len(analyzer.test_files)}")
+        print(f" Critical Files: {len(analyzer.critical_files)}")
+    elif args.command == 'validate':
+        required_files = ['AGENTS.md', 'CLAUDE.md', '.cursorrules', '.agentic-config.json']
+        missing = [f for f in required_files if not Path(f).exists()]
+        if missing:
+            print(f"* Missing: {', '.join(missing)}")
+            print(f"Run: braxis generate")
+            sys.exit(1)
+        else:
+            print(f"* All context files present")
+            print(f"Agent Readiness: {analyzer.total_score}/100 ({analyzer.tier})")
+
+
+if __name__ == '__main__':
+    main()

braxis-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

braxis-1.0.0/setup.py

@@ -0,0 +1,10 @@
+from setuptools import setup
+
+setup(
+    name="braxis",
+    version="1.0.0",
+    author="Jayakrishna Ichapurapu",
+    description="Auto-generate context files for AI agents",
+    license="MIT",
+    python_requires=">=3.8",
+)

braxis-1.0.0/tests/test_braxis.py

@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""
+Unit tests for Braxis - AI agent context file generator.
+Uses unittest for compatibility without external dependencies.
+"""
+import os
+import sys
+import json
+import unittest
+import tempfile
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+from braxis import BraxisAnalyzer
+
+
+class TestValidateProjectPath(unittest.TestCase):
+    """Tests for project path validation."""
+
+    def test_validate_valid_path(self):
+        """Test validation of valid project path."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            analyzer = BraxisAnalyzer(tmpdir)
+            self.assertEqual(analyzer.project_path, Path(tmpdir).resolve())
+
+    def test_validate_empty_path(self):
+        """Test validation rejects empty path."""
+        with self.assertRaises(ValueError):
+            BraxisAnalyzer("")
+
+    def test_validate_nonexistent_path(self):
+        """Test validation rejects nonexistent path."""
+        with self.assertRaises(FileNotFoundError):
+            BraxisAnalyzer("/nonexistent/path/12345")
+
+    def test_validate_file_not_directory(self):
+        """Test validation rejects file path."""
+        with tempfile.NamedTemporaryFile() as tmpfile:
+            with self.assertRaises(NotADirectoryError):
+                BraxisAnalyzer(tmpfile.name)
+
+    def test_validate_relative_path_conversion(self):
+        """Test that relative paths are converted to absolute."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            original_cwd = os.getcwd()
+            try:
+                os.chdir(tmpdir)
+                analyzer = BraxisAnalyzer(".")
+                self.assertTrue(analyzer.project_path.is_absolute())
+            finally:
+                os.chdir(original_cwd)
+
+
+class TestWriteFileSafely(unittest.TestCase):
+    """Tests for safe file writing functionality."""
+
+    def test_write_file_successfully(self):
+        """Test successful file write."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            analyzer = BraxisAnalyzer(tmpdir)
+            filepath = Path(tmpdir) / "test.txt"
+            content = "Test content"
+            analyzer._write_file_safely(str(filepath), content)
+            self.assertTrue(filepath.exists())
+            self.assertEqual(filepath.read_text(), content)
+
+    def test_write_file_creates_parent_directories(self):
+        """Test that parent directories are created."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            analyzer = BraxisAnalyzer(tmpdir)
+            filepath = Path(tmpdir) / "subdir" / "nested" / "test.txt"
+            content = "Test content"
+            analyzer._write_file_safely(str(filepath), content)
+            self.assertTrue(filepath.exists())
+            self.assertEqual(filepath.read_text(), content)
+
+    def test_write_file_empty_filepath(self):
+        """Test that empty filepath raises error."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            analyzer = BraxisAnalyzer(tmpdir)
+            with self.assertRaises(ValueError):
+                analyzer._write_file_safely("", "content")
+
+    def test_write_file_non_string_content(self):
+        """Test that non-string content raises error."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            analyzer = BraxisAnalyzer(tmpdir)
+            filepath = Path(tmpdir) / "test.txt"
+            with self.assertRaises(TypeError):
+                analyzer._write_file_safely(str(filepath), 123)
+
+    def test_write_file_overwrites_existing(self):
+        """Test that file write overwrites existing file."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            analyzer = BraxisAnalyzer(tmpdir)
+            filepath = Path(tmpdir) / "test.txt"
+            filepath.write_text("Old content")
+            analyzer._write_file_safely(str(filepath), "New content")
+            self.assertEqual(filepath.read_text(), "New content")
+
+    def test_write_file_cleans_temp_file(self):
+        """Test that temp files are cleaned up."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            analyzer = BraxisAnalyzer(tmpdir)
+            filepath = Path(tmpdir) / "test.txt"
+            analyzer._write_file_safely(str(filepath), "content")
+            tmp_files = list(Path(tmpdir).glob("*.tmp"))
+            self.assertEqual(len(tmp_files), 0)
+
+
+class TestBraxisAnalyzer(unittest.TestCase):
+    """Tests for BraxisAnalyzer functionality."""
+
+    def test_analyzer_initialization(self):
+        """Test analyzer initialization."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            analyzer = BraxisAnalyzer(tmpdir)
+            self.assertEqual(analyzer.files, [])
+            self.assertEqual(analyzer.test_files, [])
+            self.assertEqual(analyzer.config_files, [])
+            self.assertEqual(analyzer.build_files, [])
+            self.assertEqual(analyzer.tier, "Not Ready")
+
+    def test_scan_files(self):
+        """Test file scanning."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "test.py").write_text("# test")
+            Path(tmpdir, "main.py").write_text("# main")
+            Path(tmpdir, "config.json").write_text("{}")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer._scan_files()
+
+            self.assertGreaterEqual(len(analyzer.files), 3)
+            self.assertTrue(any("test.py" in str(f) for f in analyzer.files))
+
+    def test_detect_languages(self):
+        """Test language detection."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "test.py").write_text("# python")
+            Path(tmpdir, "script.js").write_text("// javascript")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer._scan_files()
+            analyzer._detect_languages()
+
+            self.assertIn("python", analyzer.languages)
+            self.assertIn("javascript", analyzer.languages)
+
+    def test_detect_test_files(self):
+        """Test test file detection."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "test_main.py").write_text("# test")
+            Path(tmpdir, "main_test.py").write_text("# test")
+            Path(tmpdir, "main.py").write_text("# main")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer._scan_files()
+
+            self.assertGreaterEqual(len(analyzer.test_files), 2)
+
+    def test_detect_build_system_python(self):
+        """Test Python build system detection."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "setup.py").write_text("# setup")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer._scan_files()
+            analyzer._detect_build_system()
+
+            self.assertIn("Python", analyzer.build_system)
+
+    def test_detect_build_system_npm(self):
+        """Test npm build system detection."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "package.json").write_text("{}")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer._scan_files()
+            analyzer._detect_build_system()
+
+            self.assertTrue("npm" in analyzer.build_system or "Node" in analyzer.build_system)
+
+    def test_detect_build_system_unknown(self):
+        """Test unknown build system detection."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer._scan_files()
+            analyzer._detect_build_system()
+
+            self.assertEqual(analyzer.build_system, "Unknown")
+
+    def test_calculate_score(self):
+        """Test score calculation."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "main.py").write_text("# main")
+            Path(tmpdir, "test.py").write_text("# test")
+            Path(tmpdir, "README.md").write_text("# Readme")
+            Path(tmpdir, "setup.py").write_text("# setup")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer.analyze()
+
+            self.assertTrue(hasattr(analyzer, "total_score"))
+            self.assertGreaterEqual(analyzer.total_score, 0)
+            self.assertLessEqual(analyzer.total_score, 100)
+            self.assertIn(analyzer.tier, ["Not Ready", "Agent-Aware", "AI-Native", "AI-Native-Plus", "Agent-Optimized"])
+
+    def test_generate_agents_md(self):
+        """Test AGENTS.md generation."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "test.py").write_text("# test")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer.analyze()
+            content = analyzer.generate_agents_md()
+
+            self.assertIn("AGENTS.md", content)
+            self.assertIn("Tech Stack", content)
+
+    def test_generate_claude_md(self):
+        """Test CLAUDE.md generation."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "test.py").write_text("# test")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer.analyze()
+            content = analyzer.generate_claude_md()
+
+            self.assertIn("CLAUDE.md", content)
+            self.assertIn("Project", content)
+
+    def test_generate_cursorrules(self):
+        """Test .cursorrules generation."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "test.py").write_text("# test")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer.analyze()
+            content = analyzer.generate_cursorrules()
+
+            self.assertIn("Cursor Rules", content)
+
+    def test_generate_agentic_config(self):
+        """Test .agentic-config.json generation."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "test.py").write_text("# test")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer.analyze()
+            content = analyzer.generate_agentic_config()
+
+            config = json.loads(content)
+            self.assertIn("name", config)
+            self.assertIn("language", config)
+            self.assertIn("agent_readiness_score", config)
+            self.assertIn("tier", config)
+
+    def test_analyze_full_workflow(self):
+        """Test complete analysis workflow."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "main.py").write_text("# main")
+            Path(tmpdir, "test.py").write_text("import unittest")
+            Path(tmpdir, "README.md").write_text("# Project")
+            Path(tmpdir, "setup.py").write_text("# setup")
+            Path(tmpdir, "config.json").write_text("{}")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer.analyze()
+
+            self.assertGreater(len(analyzer.files), 0)
+            self.assertGreater(len(analyzer.languages), 0)
+            self.assertGreater(analyzer.total_score, 0)
+            self.assertNotEqual(analyzer.tier, "Not Ready")
+
+
+class TestEdgeCases(unittest.TestCase):
+    """Tests for edge cases and error handling."""
+
+    def test_empty_directory(self):
+        """Test analysis of empty directory."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer.analyze()
+            self.assertGreater(len(analyzer.files), -1)
+            self.assertGreater(analyzer.total_score, 0)
+
+    def test_special_characters_in_path(self):
+        """Test handling of special characters in file paths."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            special_dir = Path(tmpdir) / "test-dir_123"
+            special_dir.mkdir()
+
+            analyzer = BraxisAnalyzer(str(special_dir))
+            self.assertEqual(analyzer.project_path, special_dir.resolve())
+
+    def test_large_file_scanning(self):
+        """Test handling of large files."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            large_file = Path(tmpdir) / "large.py"
+            large_file.write_text("# " + "x" * 10000)
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer.analyze()
+            self.assertIn(large_file, analyzer.files)
+
+    def test_ignored_directories(self):
+        """Test that common build directories are ignored."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            (Path(tmpdir) / ".git").mkdir()
+            (Path(tmpdir) / ".git" / "config").write_text("git")
+            (Path(tmpdir) / "node_modules").mkdir()
+            (Path(tmpdir) / "node_modules" / "pkg.js").write_text("js")
+
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer._scan_files()
+
+            git_files = [f for f in analyzer.files if ".git" in str(f)]
+            node_files = [f for f in analyzer.files if "node_modules" in str(f)]
+
+            self.assertEqual(len(git_files), 0)
+            self.assertEqual(len(node_files), 0)
+
+    def test_file_write_with_unicode(self):
+        """Test writing files with unicode content."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            analyzer = BraxisAnalyzer(tmpdir)
+            filepath = Path(tmpdir) / "unicode.txt"
+            content = "Unicode test: 你好世界 🚀"
+            analyzer._write_file_safely(str(filepath), content)
+            self.assertEqual(filepath.read_text(encoding='utf-8'), content)
+
+    def test_score_breakdown_keys(self):
+        """Test that score breakdown has expected keys."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "test.py").write_text("# test")
+            analyzer = BraxisAnalyzer(tmpdir)
+            analyzer.analyze()
+
+            expected_keys = ['Architecture', 'Testing', 'Dependencies', 'Conventions',
+                           'Entry Points', 'Security', 'Build', 'Documentation']
+            for key in expected_keys:
+                self.assertIn(key, analyzer.score_breakdown)
+
+
+if __name__ == '__main__':
+    unittest.main()