Skip to content

Commit 4c274d8

Browse files
JoshuaEstesJoshuaEstes
authored
Adding AGENTS.md to repo (SonsOfPHP#242)
1 parent 8774f0e commit 4c274d8

File tree

51 files changed

+844
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+844
-0
lines changed

‎AGENTS.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Agents Guide for Sons of PHP Monorepo
2+
3+
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.
4+
5+
## Repo Layout
6+
7+
- Root: build tooling (`Makefile`, composer), shared configs, CI inputs.
8+
- Code: packages live under `src/SonsOfPHP/*`, typically with `src/` and `Tests/` subfolders.
9+
- Docs: developer documentation in `docs/` with a GitBook-style `SUMMARY.md`.
10+
- Tools: development tools vendored under `tools/` (phpunit, psalm, rector, php-cs-fixer, etc.).
11+
12+
## Ground Rules
13+
14+
- Prefer minimal, targeted changes; avoid refactors beyond the task scope.
15+
- Never edit anything under any `vendor/` directory or generated artifacts like `dist/`.
16+
- Maintain backward compatibility for public APIs unless explicitly instructed otherwise.
17+
- Update relevant docs under `docs/` when behavior or public APIs change.
18+
- Keep code style consistent; use provided tooling to format, lint, and check types.
19+
20+
## Setup
21+
22+
- Install dependencies once at the repo root:
23+
- `make install`
24+
25+
## Common Tasks
26+
27+
- Run tests (entire repo):
28+
- `make test`
29+
- Run tests (limit to a package):
30+
- `PHPUNIT_OPTIONS='path/to/package/Tests' make test`
31+
- Code style (dry-run):
32+
- `make php-cs-fixer`
33+
- Static analysis (Psalm):
34+
- `make psalm`
35+
- Rector & style upgrades (may modify files):
36+
- `make upgrade-code`
37+
- Lint PHP syntax:
38+
- `make lint`
39+
- Coverage report:
40+
- `make coverage`
41+
42+
## When Editing a Package
43+
44+
- Work inside that package directory (e.g. `src/SonsOfPHP/Component/Clock`).
45+
- Put new source under that package’s `src/`; add tests under its `Tests/`.
46+
- Use the package-focused test command above to tighten feedback cycles.
47+
48+
## Documentation
49+
50+
- Update `docs/` to reflect user-facing changes.
51+
- Add or modify the most relevant page (e.g., `docs/components/*.md`, `docs/contracts/*.md`, or `docs/symfony-bundles/*.md`).
52+
- If adding a new page, ensure it’s listed in `docs/SUMMARY.md`.
53+
54+
## Pull Request Checklist
55+
56+
- Build passes: `make test` (optionally with coverage).
57+
- Code quality passes: `make php-cs-fixer`, `make psalm`, and (if applicable) `make upgrade-code`.
58+
- Docs updated where needed.
59+
- No changes to `vendor/` or generated artifacts.
60+

‎docs/AGENTS.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Agents Guide for Docs
2+
3+
This project’s documentation lives in `docs/` and is organized for GitBook consumption with a table of contents in `SUMMARY.md`.
4+
5+
## Principles
6+
7+
- Keep docs accurate, concise, and task-oriented.
8+
- Prefer small, incremental updates alongside code changes.
9+
- Mirror package names and concepts used in code for easy navigation.
10+
11+
## Where to Edit
12+
13+
- Components: `docs/components/*.md`
14+
- Contracts: `docs/contracts/*.md`
15+
- Symfony bundles: `docs/symfony-bundles/*.md`
16+
- Bard CLI: `docs/bard/*.md`
17+
- General/Project: `docs/README.md`, `docs/getting-help.md`, etc.
18+
19+
## Table of Contents
20+
21+
- When adding new pages, update `docs/SUMMARY.md` to include them in the navigation.
22+
23+
## Writing Style
24+
25+
- Use clear headings and short sections.
26+
- Include small code examples (PHP) when helpful.
27+
- Document public APIs and noteworthy behavior changes.
28+
- Link to related pages within `docs/` when context helps.
29+
30+
## Quick Checks
31+
32+
- Cross-check names, namespaces, and examples with the code.
33+
- Keep examples runnable where possible.
34+
- Avoid duplicating content that can be linked.
35+

‎src/SonsOfPHP/Bard/AGENTS.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bard
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bard/src`
6+
- Tests: `src/SonsOfPHP/Bard/Tests`
7+
- Do not edit: `src/SonsOfPHP/Bard/vendor/`, `src/SonsOfPHP/Bard/dist/`
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bard/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+
16+
## Notes
17+
18+
- Keep CLI outputs stable; update docs in `docs/bard/` if UX changes.
19+
- Avoid committing built artifacts under `dist/`.
20+

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

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Aws/Filesystem
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Aws/Filesystem/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Aws/Filesystem/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Aws/Filesystem/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+
16+
## Notes
17+
18+
- Ensure AWS-related integrations remain optional and well-typed.
19+
- If user-facing behavior changes, update related docs under `docs/components/` or integration sections as applicable.
20+

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/Collections/Pager
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Doctrine/Collections/Pager/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Doctrine/Collections/Pager/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/Collections/Pager/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+
16+
## Notes
17+
18+
- Keep Doctrine-related integrations loosely coupled and optional.
19+

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/EventSourcing
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Doctrine/EventSourcing/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Doctrine/EventSourcing/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/EventSourcing/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/ORM/Pager
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Doctrine/ORM/Pager/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Doctrine/ORM/Pager/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/ORM/Pager/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/LiipImagine/Filesystem
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/LiipImagine/Filesystem/src`
6+
- Tests: `src/SonsOfPHP/Bridge/LiipImagine/Filesystem/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/LiipImagine/Filesystem/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Symfony/Cqrs
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Symfony/Cqrs/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Symfony/Cqrs/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Symfony/Cqrs/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+

0 commit comments

Comments
 (0)