Adding AGENTS.md to repo

AGENTS.md

@@ -0,0 +1,60 @@
+# Agents Guide for Sons of PHP Monorepo
+
+This repository is a PHP monorepo containing many packages under `src/`. This guide provides consistent instructions for AI coding agents to work safely and effectively across the codebase.
+
+## Repo Layout
+
+- Root: build tooling (`Makefile`, composer), shared configs, CI inputs.
+- Code: packages live under `src/SonsOfPHP/*`, typically with `src/` and `Tests/` subfolders.
+- Docs: developer documentation in `docs/` with a GitBook-style `SUMMARY.md`.
+- Tools: development tools vendored under `tools/` (phpunit, psalm, rector, php-cs-fixer, etc.).
+
+## Ground Rules
+
+- Prefer minimal, targeted changes; avoid refactors beyond the task scope.
+- Never edit anything under any `vendor/` directory or generated artifacts like `dist/`.
+- Maintain backward compatibility for public APIs unless explicitly instructed otherwise.
+- Update relevant docs under `docs/` when behavior or public APIs change.
+- Keep code style consistent; use provided tooling to format, lint, and check types.
+
+## Setup
+
+- Install dependencies once at the repo root:
+  - `make install`
+
+## Common Tasks
+
+- Run tests (entire repo):
+  - `make test`
+- Run tests (limit to a package):
+  - `PHPUNIT_OPTIONS='path/to/package/Tests' make test`
+- Code style (dry-run):
+  - `make php-cs-fixer`
+- Static analysis (Psalm):
+  - `make psalm`
+- Rector & style upgrades (may modify files):
+  - `make upgrade-code`
+- Lint PHP syntax:
+  - `make lint`
+- Coverage report:
+  - `make coverage`
+
+## When Editing a Package
+
+- Work inside that package directory (e.g. `src/SonsOfPHP/Component/Clock`).
+- Put new source under that package’s `src/`; add tests under its `Tests/`.
+- Use the package-focused test command above to tighten feedback cycles.
+
+## Documentation
+
+- Update `docs/` to reflect user-facing changes.
+- Add or modify the most relevant page (e.g., `docs/components/*.md`, `docs/contracts/*.md`, or `docs/symfony-bundles/*.md`).
+- If adding a new page, ensure it’s listed in `docs/SUMMARY.md`.
+
+## Pull Request Checklist
+
+- Build passes: `make test` (optionally with coverage).
+- Code quality passes: `make php-cs-fixer`, `make psalm`, and (if applicable) `make upgrade-code`.
+- Docs updated where needed.
+- No changes to `vendor/` or generated artifacts.
+

docs/AGENTS.md

@@ -0,0 +1,35 @@
+# Agents Guide for Docs
+
+This project’s documentation lives in `docs/` and is organized for GitBook consumption with a table of contents in `SUMMARY.md`.
+
+## Principles
+
+- Keep docs accurate, concise, and task-oriented.
+- Prefer small, incremental updates alongside code changes.
+- Mirror package names and concepts used in code for easy navigation.
+
+## Where to Edit
+
+- Components: `docs/components/*.md`
+- Contracts: `docs/contracts/*.md`
+- Symfony bundles: `docs/symfony-bundles/*.md`
+- Bard CLI: `docs/bard/*.md`
+- General/Project: `docs/README.md`, `docs/getting-help.md`, etc.
+
+## Table of Contents
+
+- When adding new pages, update `docs/SUMMARY.md` to include them in the navigation.
+
+## Writing Style
+
+- Use clear headings and short sections.
+- Include small code examples (PHP) when helpful.
+- Document public APIs and noteworthy behavior changes.
+- Link to related pages within `docs/` when context helps.
+
+## Quick Checks
+
+- Cross-check names, namespaces, and examples with the code.
+- Keep examples runnable where possible.
+- Avoid duplicating content that can be linked.
+

src/SonsOfPHP/Bard/AGENTS.md

@@ -0,0 +1,20 @@
+# Agents Guide for Package: src/SonsOfPHP/Bard
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bard/src`
+- Tests: `src/SonsOfPHP/Bard/Tests`
+- Do not edit: `src/SonsOfPHP/Bard/vendor/`, `src/SonsOfPHP/Bard/dist/`
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bard/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+
+## Notes
+
+- Keep CLI outputs stable; update docs in `docs/bard/` if UX changes.
+- Avoid committing built artifacts under `dist/`.
+

src/SonsOfPHP/Bridge/Aws/Filesystem/AGENTS.md

@@ -0,0 +1,20 @@
+# Agents Guide for Package: src/SonsOfPHP/Bridge/Aws/Filesystem
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bridge/Aws/Filesystem/src`
+- Tests: `src/SonsOfPHP/Bridge/Aws/Filesystem/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Aws/Filesystem/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+
+## Notes
+
+- Ensure AWS-related integrations remain optional and well-typed.
+- If user-facing behavior changes, update related docs under `docs/components/` or integration sections as applicable.
+

src/SonsOfPHP/Bridge/Doctrine/Collections/Pager/AGENTS.md

@@ -0,0 +1,19 @@
+# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/Collections/Pager
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bridge/Doctrine/Collections/Pager/src`
+- Tests: `src/SonsOfPHP/Bridge/Doctrine/Collections/Pager/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/Collections/Pager/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+
+## Notes
+
+- Keep Doctrine-related integrations loosely coupled and optional.
+

src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager/src`
+- Tests: `src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Bridge/Doctrine/EventSourcing/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/EventSourcing
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bridge/Doctrine/EventSourcing/src`
+- Tests: `src/SonsOfPHP/Bridge/Doctrine/EventSourcing/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/EventSourcing/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Bridge/Doctrine/ORM/Pager/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/ORM/Pager
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bridge/Doctrine/ORM/Pager/src`
+- Tests: `src/SonsOfPHP/Bridge/Doctrine/ORM/Pager/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/ORM/Pager/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Bridge/LiipImagine/Filesystem/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Bridge/LiipImagine/Filesystem
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bridge/LiipImagine/Filesystem/src`
+- Tests: `src/SonsOfPHP/Bridge/LiipImagine/Filesystem/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/LiipImagine/Filesystem/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Bridge/Symfony/Cqrs/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Bridge/Symfony/Cqrs
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bridge/Symfony/Cqrs/src`
+- Tests: `src/SonsOfPHP/Bridge/Symfony/Cqrs/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Symfony/Cqrs/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Bridge/Symfony/EventSourcing/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Bridge/Symfony/EventSourcing
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bridge/Symfony/EventSourcing/src`
+- Tests: `src/SonsOfPHP/Bridge/Symfony/EventSourcing/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Symfony/EventSourcing/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Bridge/Twig/Money/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Bridge/Twig/Money
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bridge/Twig/Money/src`
+- Tests: `src/SonsOfPHP/Bridge/Twig/Money/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Twig/Money/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Bundle/Cqrs/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Bundle/Cqrs
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bundle/Cqrs/src`
+- Tests: `src/SonsOfPHP/Bundle/Cqrs/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bundle/Cqrs/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Bundle/FeatureToggleBundle/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Bundle/FeatureToggleBundle
+
+## Scope
+
+- Source: `src/SonsOfPHP/Bundle/FeatureToggleBundle/src`
+- Tests: `src/SonsOfPHP/Bundle/FeatureToggleBundle/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bundle/FeatureToggleBundle/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Component/Assert/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Component/Assert
+
+## Scope
+
+- Source: `src/SonsOfPHP/Component/Assert/src`
+- Tests: `src/SonsOfPHP/Component/Assert/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Component/Assert/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Component/Cache/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Component/Cache
+
+## Scope
+
+- Source: `src/SonsOfPHP/Component/Cache/src`
+- Tests: `src/SonsOfPHP/Component/Cache/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Component/Cache/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Component/Clock/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Component/Clock
+
+## Scope
+
+- Source: `src/SonsOfPHP/Component/Clock/src`
+- Tests: `src/SonsOfPHP/Component/Clock/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Component/Clock/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Component/Container/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Component/Container
+
+## Scope
+
+- Source: `src/SonsOfPHP/Component/Container/src`
+- Tests: `src/SonsOfPHP/Component/Container/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Component/Container/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Component/Cookie/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Component/Cookie
+
+## Scope
+
+- Source: `src/SonsOfPHP/Component/Cookie/src`
+- Tests: `src/SonsOfPHP/Component/Cookie/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Component/Cookie/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+

src/SonsOfPHP/Component/Cqrs/AGENTS.md

@@ -0,0 +1,15 @@
+# Agents Guide for Package: src/SonsOfPHP/Component/Cqrs
+
+## Scope
+
+- Source: `src/SonsOfPHP/Component/Cqrs/src`
+- Tests: `src/SonsOfPHP/Component/Cqrs/Tests`
+- Do not edit: any `vendor/` directories
+
+## Workflows
+
+- Install once at repo root: `make install`
+- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Component/Cqrs/Tests' make test`
+- Style and static analysis: `make php-cs-fixer` and `make psalm`
+- Upgrade code (may modify files): `make upgrade-code`
+