Add AGENTS.md to outline contribution guidelines and project rules

Author: myckhel

AGENTS.md

@@ -0,0 +1,89 @@
+# AGENTS.md
+
+## Purpose
+This repository is a Laravel package (`binkode/laravel-paystack`) that wraps Paystack APIs for Laravel apps. Use these rules to keep contributions safe, compatible, and consistent.
+
+## Project Facts (Source of Truth)
+- Package type: Composer library (`type: package`)
+- Namespace: `Binkode\\Paystack\\`
+- Runtime dependency target: `illuminate/support ^8|^9|^10|^11`
+- Test framework: PHPUnit via `composer test`
+- Package test harness: `orchestra/testbench`
+
+## Non-Negotiable Rules
+- Preserve backward compatibility for public APIs in `src/Support/*`, routes, config keys, and facade/provider wiring.
+- Prefer minimal, focused changes over broad refactors.
+- Do not introduce breaking signature or route changes unless explicitly requested.
+- Add or update tests for behavior changes.
+- Update `readme.md` when public usage changes.
+
+## Code Style and Compatibility
+- Follow existing style in this codebase for spacing, naming, and method layout.
+- Keep syntax compatible with Laravel 8-11 ecosystem constraints.
+- Avoid introducing framework-version-specific helpers unless guarded.
+- Reuse existing abstractions before adding new layers.
+
+## Package Architecture Rules
+- HTTP calls belong in support classes using `Binkode\\Paystack\\Traits\\Request`.
+- Route exposure is centralized in `src/routes.php`.
+- Controllers are thin adapters that delegate to support classes.
+- Service container bindings and route/config registration stay in `src/PaystackServiceProvider.php`.
+- Configuration keys and defaults stay in `config/paystack.php`.
+
+## Endpoint Addition Checklist
+When adding or changing a Paystack endpoint:
+1. Implement or update method in the relevant class under `src/Support/`.
+2. If route exposure is required, register/update route entry in `src/routes.php`.
+3. Ensure controller dispatch maps correctly to support method.
+4. Add tests for success and failure behavior.
+5. Update usage docs in `readme.md` if public surface changed.
+
+## Testing Rules
+- Run `composer test` after code changes.
+- For HTTP behavior, use Laravel HTTP fakes; do not rely on live Paystack calls.
+- Validate both happy path and failed response handling.
+- If tests cannot run locally, report exactly why.
+
+## Safe Change Boundaries
+- Keep edits scoped to files needed for the task.
+- Do not rename classes, namespaces, config keys, or route paths without explicit approval.
+- Avoid dependency additions unless required and justified.
+
+## High-Signal Prompting Template (Use for Codex Requests)
+Use this template for best results:
+
+```md
+Task: <one clear outcome>
+Context: <feature/bug + why it matters>
+Scope: <files allowed to change>
+Constraints: <BC rules, style, versions, no new deps, etc.>
+Acceptance Criteria:
+- <observable behavior 1>
+- <observable behavior 2>
+Tests:
+- <exact command, usually `composer test`>
+Deliverable:
+- <expected summary format, e.g., changed files + rationale>
+```
+
+## Example Prompt
+```md
+Task: Add support for Paystack endpoint X in this package.
+Context: Needed by merchants to perform Y from Laravel jobs.
+Scope: `src/Support/X.php`, `src/routes.php`, `src/Http/Controllers/XController.php`, `tests/*`, `readme.md`.
+Constraints: Keep backward compatibility, no new dependencies, match existing code style.
+Acceptance Criteria:
+- New support method calls the correct endpoint with expected HTTP method.
+- Route dispatch reaches the support method.
+- Failure responses are handled consistently with existing request trait behavior.
+Tests:
+- `composer test`
+Deliverable:
+- Patch + short summary + any follow-up risks.
+```
+
+## Definition of Done
+- Code compiles and aligns with existing package patterns.
+- Tests added/updated and executed (or blocker clearly stated).
+- Docs updated when behavior or API usage changed.
+- No unintended API or routing regressions.