From f6cfdba5a820182ad6902839cbd989dcff95c566 Mon Sep 17 00:00:00 2001 From: Jayakrishna Ichapurapu Date: Sun, 11 Oct 2026 02:05:57 -0500 Subject: [PATCH] feat: Add/update AGENTS.md for AI agent guidance Generated by Braxis https://github.com/jaykrishna316/braxis Co-Authored-By: Jayakrishna Ichapurapu --- .agentic-config.json | 135 +++++++++++++++++++++++ .cursorrules | 77 +++++++++++++ AGENTS.md | 253 +++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 49 +++++++++ 4 files changed, 514 insertions(+) create mode 100644 .agentic-config.json create mode 100644 .cursorrules create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/.agentic-config.json b/.agentic-config.json new file mode 100644 index 0000000000..e4e41bec94 --- /dev/null +++ b/.agentic-config.json @@ -0,0 +1,135 @@ +{ + "metadata": { + "project_name": "httpie", + "description": "A Python project with setuptools", + "generated_by": "Braxis", + "generated_at": "2026-10-11T02:05:57.513057", + "schema_version": "1.0" + }, + "project": { + "languages": [ + "python", + "ruby" + ], + "primary_language": "python", + "build_system": "setuptools", + "architecture": "single-package", + "is_monorepo": false, + "monorepo_type": null, + "subsystems": [] + }, + "ai_readiness": { + "overall_score": 71, + "tier": "AI-Native-Plus", + "dimensions": { + "architecture": { + "score": 0, + "reason": "Code organization and modularity" + }, + "testing": { + "score": 15, + "reason": "104 test files found" + }, + "dependencies": { + "score": 12, + "reason": "Dependency management and version pinning" + }, + "conventions": { + "score": 6, + "reason": "Consistency in naming and patterns" + }, + "entry_points": { + "score": 0, + "reason": "0 critical files identified" + }, + "security": { + "score": 15, + "reason": "Input validation and error handling" + }, + "build": { + "score": 10, + "reason": "Build system clarity and configuration" + }, + "documentation": { + "score": 8, + "reason": "README and code documentation" + } + } + }, + "development": { + "setup_command": "pip install -e . && uv sync --all-groups", + "test_command": "pytest", + "lint_command": "ruff check .", + "format_command": "ruff format .", + "dev_server_command": null, + "prerequisites": { + "language_version": "3.9+", + "package_manager": "pip or uv", + "key_tools": [ + "pytest", + "ruff", + "mypy" + ] + } + }, + "architecture": { + "pattern": "single-package project", + "main_entry": "Standard layout", + "key_modules": [], + "layers": [ + "CLI interface (if applicable)", + "Business logic", + "Utilities and helpers" + ] + }, + "mcp_servers": [], + "core_principles": [ + "Modularity - Code organized by functionality", + "Testability - Comprehensive test coverage", + "Clarity - Code easy for AI agents to understand", + "Consistency - Uniform patterns throughout" + ], + "contribution_criteria": { + "what_we_want": [ + "Bug fixes with test coverage", + "Code quality improvements", + "Test coverage increases", + "Documentation improvements", + "Performance optimizations" + ], + "what_we_dont_want": [ + "New dependencies without justification", + "Code that reduces test coverage", + "Inconsistent naming or style", + "Dead code or commented code" + ] + }, + "contribution_boundaries": { + "project_scale": "medium", + "suggestion": "This project is growing. Consider defining clear contribution scope." + }, + "commands": { + "setup": { + "command": "pip install -e . && uv sync --all-groups", + "description": "Install dependencies and set up development environment" + }, + "test": { + "command": "pytest", + "description": "Run all tests" + }, + "lint": { + "command": "ruff check .", + "description": "Check code style and quality" + }, + "format": { + "command": "ruff format .", + "description": "Format code to project standards" + } + }, + "testing": { + "framework": "pytest", + "total_tests": 104, + "pass_rate": 100, + "run_command": "pytest" + } +} \ No newline at end of file diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000000..8117dfadcd --- /dev/null +++ b/.cursorrules @@ -0,0 +1,77 @@ +# Cursor Rules for httpie + +## What This Project Does + +**Language:** Python | **Build:** setuptools + +**AI Readiness Score:** 71/100 (AI-Native-Plus) + +## Must-Follow Rules + +### Code Style & Formatting + +1. Use **ruff** for formatting: `ruff format .` +2. Use **ruff** for linting: `ruff check .` +3. Python conventions: **snake_case** for functions/variables, **PascalCase** for classes +4. Type hints: Required for all public functions using **mypy** for checking +5. Docstrings: Use triple-quoted strings for all public functions and classes +6. No commented-out code, no dead code +7. Max line length: 100 characters + +### Testing +1. Framework: pytest +2. Test file naming: `test_*.py` or `*_test.py` +3. Test discovery: `pytest` finds and runs all tests +4. Fixtures: Use pytest fixtures for setup/teardown +5. Coverage: Maintain 80%+ coverage for critical paths +6. Run before commit: `pytest -v` + +### Imports & Dependencies +1. Use absolute imports, not relative imports (unless necessary) +2. Group imports: stdlib, third-party, local (isort style) +3. No wildcard imports (`from module import *`) +4. Pin versions in requirements.txt/pyproject.toml +5. Avoid circular dependencies + +### Error Handling +1. Be specific with exception types (not bare `except:`) +2. Log errors before re-raising +3. Validate all function arguments at entry points +4. Use try/except at system boundaries (I/O, network, DB) + + +## Scoring Dimensions (What Matters) + +These 8 areas drive AI readiness. Focus on these when making changes: + +1. **Architecture** (0/15) - Code organization and modularity +2. **Testing** (15/15) - Test coverage and quality +3. **Dependencies** (12/12) - Dependency management +4. **Conventions** (6/10) - Consistent patterns +5. **Entry Points** (0/10) - Clear main/start locations +6. **Security** (15/15) - Input validation and error handling +7. **Build** (10/10) - Clear build/setup instructions +8. **Documentation** (8/8) - Code and project documentation + +## Before You Commit + +```bash +# Format code +ruff format . + +# Lint check +ruff check . + +# Run tests +pytest +``` + +All checks must pass before committing. + +## Questions? + +See AGENTS.md for detailed documentation on architecture, development workflow, and testing strategy. + +--- + +*Generated by Braxis - language-aware rules for Python projects* diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..f6a0168930 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,253 @@ +# AGENTS.md + +Context file for AI agents working on httpie. + +**Dual Format**: This file combines Category A (Operations Manual) and Category B (Context Guide) for comprehensive agent guidance. + +**Domain Detected:** Agent / Chatbot (Based on codebase patterns) + +## Project Overview + +httpie is a Python project using setuptools. + +**Key Info:** +- **Primary Language:** Python +- **Build System:** setuptools +- **Test Framework:** pytest +- **Total Files:** 265 +- **Test Files:** 104 +- **AI Readiness Score:** 71/100 (AI-Native-Plus) + +--- + +## 🚨 AI Policy & Operations + +Extracted from CONTRIBUTING.md - operational constraints and procedures. + +### Setup & Environment + +- Creates an isolated Python virtual environment inside `./venv` (via the standard library [venv](https://docs.python.org/3/library/venv.html) tool); +- installs all dependencies and also installs HTTPie (in editable mode so that the `http` command will point to your working copy). +- and runs tests (It is the same as running `make install test`). + + + +## 🤖 Agent/Chatbot Architecture + +This is an AI agent or dialogue system project. + +### Key Patterns Detected + +- **Intent Handling:** The project processes user intents and maps them to actions +- **Entity Extraction:** Named entity recognition and slot filling for dialogue context +- **Conversation Management:** Multi-turn dialogue flows with context preservation +- **Tool Use:** Agent actions or skills that execute external operations + +### Testing Agent Conversations + +When writing tests for dialogue systems: + +1. **Conversation Flows:** Test end-to-end dialogue paths, not individual components +2. **Intent Accuracy:** Verify correct intent detection for various phrasings +3. **Entity Extraction:** Test slot filling accuracy and edge cases +4. **Context Preservation:** Ensure multi-turn conversations maintain state correctly +5. **Action Execution:** Mock external actions and verify correct invocation +6. **Fallback Handling:** Test graceful degradation when confidence is low + + + +### Detected Frameworks + +| Framework | Version | Detection Type | +|-----------|---------|-----------------| +| pytest | unknown | Direct import | +| requests | unknown | Wrapped/Re-exported | +| unittest | unknown | Direct import | + + + +## 🤖 AI Contribution Policy + +- ✅ AI-assisted contributions have special rules + +## Operational Constraints + +- ⚠️ Coverage gates are monotonic (never lower baseline) + +## Release Procedures + +- Release workflow: .github/workflows/release.yml + + + +## 🏗️ Architecture & Context Guide + +This section provides architectural context and agent-understanding for the codebase. + +### Prerequisites + +- **Python:** 3.9+ (or applicable language version) +- **Package Manager:** pip or uv +- **Test Runner:** pytest + + + +### Project Structure + +``` +httpie/ +├── Makefile +├── setup.py +├── setup.cfg +├── httpie/ # Source code +├── tests/ # Test suite (104 files) +└── README.md # Project documentation +``` + +### Architecture Overview + +#### Key Components +- **Main Entry:** Standard layout +- **Test Suite:** 104 test files +- **Build Configuration:** Makefile, setup.py, setup.cfg + +#### Design Principles + +1. **Modularity** - Code organized by functionality with clear separation of concerns +2. **Testability** - Comprehensive test coverage across critical paths +3. **Clarity** - Explicit naming and structure for AI agent understanding +4. **Consistency** - Uniform patterns and conventions throughout codebase +5. **Maintainability** - Well-documented code with clear intent + +### Directory Map + +| Directory | Purpose | +|-----------|----------| +| `docs/` | Documentation | +| `tests/` | Test suite | + + +### Development Workflow + +#### Initial Setup + +```bash +git clone https://github.com/YOUR_ORG/httpie.git +cd httpie +pip install -e . +# or +uv sync --all-groups +``` + +#### Development Commands + +**Running Tests:** +```bash +pytest # Run all tests +pytest tests/ # Run specific test directory +pytest -v # Verbose output with test names +pytest -x # Stop on first failure +coverage run -m pytest && coverage report # With coverage report +``` + +#### Code Quality +```bash +ruff check . # Lint with ruff +ruff format . # Format code +mypy . # Type checking (if configured) +``` + +### Code Style & Conventions + +- **Naming:** Use snake_case for functions and variables +- **Type Hints:** Yes (strongly encouraged) +- **Error Handling:** Yes - handle errors at boundaries; let exceptions propagate when another layer owns recovery +- **Logging:** No +- **Testing:** Yes - write tests alongside code changes + +### Testing Strategy + +**Framework:** pytest +**Test Files:** 104 found + +Before committing: +1. Run the full test suite: `pytest` +2. Ensure all tests pass +3. Check type hints: `mypy .` +4. Format code: `ruff format .` + +### Writing Documentation + +When updating docs: +1. Always include explanatory text before code snippets +2. Describe *why* and *what* before showing *how* +3. Keep sections focused on a single concept +4. Use clear, concrete examples + +### Contributing Guidelines + +This project has a detailed contribution guide at **`CONTRIBUTING.md`**. + +**Key Requirements:** +- **Performance Work**: Requires benchmarks and performance metrics in PR description + +**Before submitting:** +1. Read `CONTRIBUTING.md` in full +2. Check recent merged PRs for patterns +3. Follow the specific requirements above + +### Common Patterns + +When contributing to this project: +1. Read existing code in the area you're modifying +2. Follow the established patterns and style +3. Write tests for new functionality +4. Use clear, descriptive variable and function names +5. Add docstrings for public APIs +6. Update tests when changing behavior + +### What We Value + +✅ Well-tested code with clear intent +✅ Consistent code style and naming conventions +✅ Code that is easy for AI agents to understand +✅ Clear, descriptive commit messages +✅ Modular, reusable components +✅ Comprehensive documentation + +### What We Avoid + +❌ Large functions doing multiple things +❌ Commented-out dead code +❌ Inconsistent naming or patterns +❌ Unclear error messages +❌ Unexplained magic numbers or strings +❌ Skipped tests or test TODOs + +### AI Readiness Dimensions (Scoring) + +This project is evaluated across 8 dimensions: + +1. **Architecture** (0/100) - Code organization and modularity +2. **Testing** (15/100) - Test coverage and quality +3. **Dependencies** (12/100) - Dependency management +4. **Conventions** (6/100) - Consistent patterns +5. **Entry Points** (0/100) - Clear main/start locations +6. **Security** (15/100) - Input validation and error handling +7. **Build** (10/100) - Clear build/setup instructions +8. **Documentation** (8/100) - Code and project documentation + +### Next Steps + +Before making changes: +1. Read relevant source files to understand the existing code +2. Look at existing tests for similar functionality +3. Follow the patterns you see in the codebase +4. Write tests for your changes +5. Run `pytest` to verify nothing breaks +6. Run code quality checks: `ruff check . && mypy .` +7. Format your code: `ruff format .` + +--- + +*Generated by Braxis - keeping AI agents in sync with your code* diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..29735289a2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,49 @@ +# CLAUDE.md + +@AGENTS.md + +This project uses AGENTS.md as the standard agent context. Claude Code loads it automatically via the @AGENTS.md import above. + +## Project: httpie + +**Language:** Python | **Build:** setuptools | **Score:** 71/100 + +--- + +## Quick Reference for Claude + +### Before You Start +1. **Read AGENTS.md first** for full project architecture and workflow +2. **Check the caveats above** — they're extracted from this project's docs +3. **Run tests locally** before suggesting code changes +4. **Follow AGENTS.md conventions** for code style + +### Key Commands +```bash +# Regenerate AI context files +braxis generate + +# View AI readiness score +braxis score + +# See score trends +braxis history --trends +``` + +### Testing Workflow +```bash +pytest +``` + +### Code Quality +```bash +ruff check . # Lint +ruff format . # Format +mypy . # Type check +``` + +--- + +See AGENTS.md for complete project documentation. + +*Generated by Braxis - keeping AI agents in sync with httpie*