Add comprehensive AI agent guidelines for Claude, Cursor, and GitHub Copilot

.claude/CLAUDE.md

@@ -0,0 +1,46 @@
+# Claude AI Agent Instructions for Faraday
+
+## Overview
+You are working on the **Faraday** repository, a Ruby HTTP client library with a middleware-based architecture. Before making any code changes or suggestions, you **must** read and follow the comprehensive guidelines in `.ai/guidelines.md`.
+
+## Primary Directive
+**Always reference `.ai/guidelines.md`** for:
+- Code style and structure conventions
+- Middleware implementation patterns
+- Adapter development guidelines
+- Testing requirements with RSpec
+- Documentation standards (YARD)
+- Contribution workflow
+
+## Self-Maintaining Responsibility
+As a Claude AI agent, you are responsible for:
+1. **Reading** `.ai/guidelines.md` before every contribution
+2. **Following** all Faraday-specific conventions outlined there
+3. **Proposing updates** to `.ai/guidelines.md` when you identify:
+   - New code patterns not yet documented
+   - Changes to existing conventions
+   - Improved practices that should become standard
+   - Inconsistencies between the guidelines and actual codebase
+
+## Key Faraday Concepts
+- **Middleware Architecture**: All middleware inherit from `Faraday::Middleware` and use hooks (`on_request`, `on_complete`, `on_error`)
+- **Adapter Pattern**: Adapters extend `Faraday::MiddlewareRegistry` and implement `call`, `build_connection`, etc.
+- **Registry System**: Both middleware and adapters register themselves with unique keys
+- **Testing**: Use RSpec with shared examples, stubs instead of real network calls
+- **Documentation**: YARD comments for all public APIs
+
+## What NOT to Do
+- Do not provide generic Ruby or RSpec advice—focus on Faraday-specific patterns
+- Do not suggest changes that violate established conventions without first proposing guideline updates
+- Do not implement middleware or adapters without checking existing patterns in the codebase
+
+## Quick Reference
+- Main guidelines: `.ai/guidelines.md`
+- Contributing guide: `.github/CONTRIBUTING.md`
+- Example middleware: `lib/faraday/request/json.rb`
+- Example adapter: `lib/faraday/adapter/test.rb`
+- Middleware base: `lib/faraday/middleware.rb`
+
+---
+
+**Remember**: Keep `.ai/guidelines.md` current. If you notice any drift between documentation and reality, propose updates to maintain accuracy.

.cursorrules

@@ -0,0 +1,84 @@
+# Cursor AI Rules for Faraday Repository
+
+## Primary Guidelines Reference
+**CRITICAL**: Before making any code changes, read `.ai/guidelines.md` for comprehensive Faraday-specific conventions.
+
+## About Faraday
+Faraday is a Ruby HTTP client library with a middleware-based architecture similar to Rack. It provides a common interface over many HTTP adapters and uses middleware for request/response processing.
+
+## Core Responsibilities
+1. **Read First**: Always consult `.ai/guidelines.md` before contributing
+2. **Follow Conventions**: Adhere to all Faraday-specific patterns documented in guidelines
+3. **Maintain Guidelines**: Propose updates to `.ai/guidelines.md` when:
+   - You identify undocumented patterns in the codebase
+   - Existing conventions change
+   - Better practices emerge
+
+## Faraday-Specific Patterns
+
+### Middleware (See `.ai/guidelines.md` for details)
+- Inherit from `Faraday::Middleware`
+- Use `DEFAULT_OPTIONS` constant
+- Implement only needed hooks: `on_request`, `on_complete`, `on_error`
+- Register via `Faraday::Middleware.register_middleware`
+- Keep stateless; use `env` hash for state
+
+### Adapters (See `.ai/guidelines.md` for details)
+- Extend `Faraday::MiddlewareRegistry`
+- Implement `call`, `build_connection`, `close`
+- Place in `lib/faraday/adapter/`
+- Register via `Faraday::Adapter.register_middleware`
+- Support parallel requests if possible
+
+### Testing with RSpec
+- Use shared examples for adapters/middleware
+- Mock network calls; never make real HTTP requests
+- Test organization mirrors `lib/` structure
+- See `spec/support` for test helpers
+
+### Documentation
+- YARD-style comments for all public APIs
+- Update docs/ for user-facing features
+- Keep README and CHANGELOG current
+
+## Code Organization
+```
+lib/faraday/
+  ├── adapter/          # HTTP adapters
+  ├── request/          # Request middleware
+  ├── response/         # Response middleware
+  └── middleware.rb     # Base middleware class
+
+spec/faraday/
+  └── (mirrors lib structure)
+```
+
+## Quick Start Examples
+
+**Middleware Registration**:
+```ruby
+Faraday::Request.register_middleware(my_middleware: MyMiddleware)
+```
+
+**Adapter Registration**:
+```ruby
+Faraday::Adapter.register_middleware(my_adapter: MyAdapter)
+```
+
+## Contribution Workflow
+- Follow `.github/CONTRIBUTING.md`
+- Run tests: `bundle exec rspec`
+- Check style: `bundle exec rubocop`
+- Use inclusive language
+
+## Self-Maintaining Principle
+This file and `.ai/guidelines.md` must stay current with the codebase. When you detect any divergence between documentation and implementation, propose updates to keep them aligned.
+
+---
+
+**Key Files**:
+- `.ai/guidelines.md` - Complete conventions (READ THIS FIRST)
+- `.github/CONTRIBUTING.md` - Contribution process
+- `lib/faraday/middleware.rb` - Middleware base class
+- Example: `lib/faraday/request/json.rb` (middleware)
+- Example: `lib/faraday/adapter/test.rb` (adapter)

.github/copilot-instructions.md

@@ -0,0 +1,121 @@
+# GitHub Copilot Instructions for Faraday
+
+## Essential Reading
+**Before making any code suggestions**, consult `.ai/guidelines.md` for comprehensive Faraday-specific conventions and patterns.
+
+## About This Repository
+Faraday is a Ruby HTTP client library that provides:
+- A middleware-based architecture (similar to Rack)
+- A common interface over various HTTP adapters (Net::HTTP, HTTPClient, etc.)
+- Extensible request/response processing pipeline
+
+## Your Responsibilities
+As GitHub Copilot working on Faraday, you must:
+
+1. **Read & Follow**: Always reference `.ai/guidelines.md` for Faraday conventions
+2. **Stay Current**: Suggest updates to `.ai/guidelines.md` when you notice:
+   - New patterns not yet documented
+   - Changes to existing conventions
+   - Discrepancies between guidelines and actual code
+3. **Focus on Faraday**: Provide Faraday-specific guidance, not generic Ruby/RSpec tips
+
+## Core Architecture Patterns
+
+### Middleware System
+All middleware must:
+- Inherit from `Faraday::Middleware`
+- Define `DEFAULT_OPTIONS` constant if configurable
+- Implement only required hooks: `on_request`, `on_complete`, or `on_error`
+- Register with a unique key via `Faraday::Middleware.register_middleware`
+- Remain stateless (store state in `env` hash only)
+
+Example structure:
+```ruby
+module Faraday
+  class Request
+    class MyMiddleware < Middleware
+      DEFAULT_OPTIONS = { option: 'value' }.freeze
+
+      def on_request(env)
+        # Modify request
+      end
+    end
+  end
+end
+
+Faraday::Request.register_middleware(my_middleware: Faraday::Request::MyMiddleware)
+```
+
+### Adapter System
+All adapters must:
+- Extend `Faraday::MiddlewareRegistry`
+- Implement `call(env)` method
+- Implement `build_connection(env)` for connection setup
+- Implement `close` for cleanup
+- Be placed in `lib/faraday/adapter/`
+- Register via `Faraday::Adapter.register_middleware`
+
+For parallel support:
+- Include `Parallelism` module
+- Set `supports_parallel = true`
+
+### Testing Conventions
+- Use RSpec for all tests
+- Leverage shared examples for adapters and middleware (see `spec/support`)
+- Mock HTTP calls; never make real network requests
+- Follow test organization: `spec/faraday/` mirrors `lib/faraday/`
+- Test middleware: use doubles for `app` and verify hook invocations
+
+### Documentation Standards
+- Add YARD comments to all public APIs
+- Update `docs/` for user-facing features
+- Keep README.md and CHANGELOG.md current
+- Document new middleware/adapters in `docs/` folder
+
+## Project Structure
+```
+lib/faraday/
+├── adapter/              # HTTP backend adapters
+│   └── test.rb          # Test adapter (example)
+├── request/             # Request middleware
+│   ├── json.rb         # JSON encoding (example)
+│   └── authorization.rb
+├── response/            # Response middleware
+├── middleware.rb        # Base middleware class
+└── adapter.rb          # Base adapter class
+
+spec/faraday/
+└── (mirrors lib structure)
+```
+
+## Code Quality Requirements
+- Follow RuboCop style guide (`.rubocop.yml`)
+- Ensure all code passes: `bundle exec rubocop`
+- All features need tests: `bundle exec rspec`
+- Use inclusive language (see `.github/CONTRIBUTING.md`)
+
+## Contribution Process
+1. Check `.github/CONTRIBUTING.md` for workflow
+2. New features require tests and documentation
+3. Adapters/middleware should be separate gems (link from this project)
+4. Follow semantic versioning for breaking changes
+
+## Self-Maintaining Guidelines
+You are responsible for keeping `.ai/guidelines.md` accurate and current. When you identify:
+- Code patterns not reflected in guidelines
+- Convention changes
+- Better practices
+
+Propose updates to `.ai/guidelines.md` to maintain alignment with the actual codebase.
+
+## Reference Files
+- **Complete Guidelines**: `.ai/guidelines.md` (PRIMARY REFERENCE)
+- **Contribution Guide**: `.github/CONTRIBUTING.md`
+- **Middleware Base**: `lib/faraday/middleware.rb`
+- **Middleware Example**: `lib/faraday/request/json.rb`
+- **Adapter Example**: `lib/faraday/adapter/test.rb`
+- **Style Guide**: `.rubocop.yml`
+
+---
+
+**Remember**: The guidelines in `.ai/guidelines.md` are the source of truth for Faraday conventions. Keep them current and refer to them consistently.