AGENTS.md git:20260917.3d83f4cA

Immutable. This exact content is served forever at /api/v1/blob/0ed768aee7fc189d.

<!-- @generated by scripts/build.ts from content/ — DO NOT EDIT -->
# Symfony agent skill library

Version-accurate Symfony expertise for coding agents: API Platform v4, Doctrine ORM 3, TDD with Pest & PHPUnit, Messenger, security, and pragmatic architecture.

Version 0.2.0 · https://github.com/dev-toolings/superpowers-symfony

## Target versions

- symfony: 7.4 LTS / 8.x (6.4 LTS legacy)
- apiPlatform: v4 (v3 legacy)
- doctrineOrm: 3.x
- php: 8.2 – 8.4

## How to use this library

Skills are instructions, not documentation. When a task matches one, open its
`SKILL.md` and follow it literally — then open the sibling `reference.md` only
if you need the deep implementation detail.

Paths below are relative to the root of this repository.

## Runtime context

Run `./bin/symfony-context` before the first command of a session. It detects
the Symfony version, API Platform, the Docker setup, the test framework, and
prints the correctly prefixed `console`, `composer` and test commands.
Use `--format=markdown` for a readable block, `--format=env` for scripts.

## Skills (44)

### API Platform

- **api-platform-dto-resources** — Map entities to API DTOs in API Platform v4 with the Symfony Object Mapper (#[Map], stateOptions) for decoupled input/output contracts → `content/skills/api-platform-dto-resources/SKILL.md` · [reference](content/skills/api-platform-dto-resources/reference.md)
- **api-platform-filters** — Implement API Platform filters - v4 Parameters API (QueryParameter) and legacy #[ApiFilter] - for search, date, range, boolean, and custom filtering → `content/skills/api-platform-filters/SKILL.md` · [reference](content/skills/api-platform-filters/reference.md)
- **api-platform-resources** — Configure API Platform v4 resources with explicit operations, pagination, and typed OpenAPI for clean, versioned REST/GraphQL APIs → `content/skills/api-platform-resources/SKILL.md` · [reference](content/skills/api-platform-resources/reference.md)
- **api-platform-security** — Secure API Platform resources with security expressions, voters, securityPostValidation, and operation-level access control → `content/skills/api-platform-security/SKILL.md` · [reference](content/skills/api-platform-security/reference.md)
- **api-platform-serialization** — Control API Platform serialization with groups, #[Context], IRI links (readableLink/writableLink), and custom context builders → `content/skills/api-platform-serialization/SKILL.md` · [reference](content/skills/api-platform-serialization/reference.md)
- **api-platform-state-providers** — Master API Platform v4 State Providers and Processors (ProviderInterface/ProcessorInterface) to decouple data retrieval and persistence from entities → `content/skills/api-platform-state-providers/SKILL.md` · [reference](content/skills/api-platform-state-providers/reference.md)
- **api-platform-tests** — Test API Platform resources with ApiTestCase; assert collections, items, filters, JSON schema, and authentication → `content/skills/api-platform-tests/SKILL.md` · [reference](content/skills/api-platform-tests/reference.md)
- **api-platform-versioning** — Evolve API Platform APIs via deprecation (deprecationReason/sunset, RFC 8594/9745), the recommended alternative to versioning; plus path/header strategies → `content/skills/api-platform-versioning/SKILL.md` · [reference](content/skills/api-platform-versioning/reference.md)

### Doctrine ORM

- **doctrine-batch-processing** — Process large datasets with Doctrine (ORM 3 toIterable, flush+clear, bulk DQL) and memory management → `content/skills/doctrine-batch-processing/SKILL.md` · [reference](content/skills/doctrine-batch-processing/reference.md)
- **doctrine-events** — React to Doctrine entity lifecycle in Symfony with attribute listeners (#[AsDoctrineListener]/#[AsEntityListener], ORM 3) and lifecycle callbacks → `content/skills/doctrine-events/SKILL.md` · [reference](content/skills/doctrine-events/reference.md)
- **doctrine-fetch-modes** — Optimize Doctrine fetching with DTO hydration (SELECT NEW; partial removed in ORM 3), lazy loading, query hints, and DBAL 4 access → `content/skills/doctrine-fetch-modes/SKILL.md` · [reference](content/skills/doctrine-fetch-modes/reference.md)
- **doctrine-fixtures-foundry** — Create test data with Zenstruck Foundry v2 factories (PersistentObjectFactory, real objects); define states, sequences, and relationships → `content/skills/doctrine-fixtures-foundry/SKILL.md` · [reference](content/skills/doctrine-fixtures-foundry/reference.md)
- **doctrine-migrations** — Create and manage Doctrine migrations (lib 4.x) for schema versioning; handle dependencies, rollbacks, and production deployment → `content/skills/doctrine-migrations/SKILL.md` · [reference](content/skills/doctrine-migrations/reference.md)
- **doctrine-relations** — Define Doctrine entity relationships (OneToMany, ManyToMany, ManyToOne); configure cascade, orphan removal, multiple entity managers; prevent N+1 queries → `content/skills/doctrine-relations/SKILL.md` · [reference](content/skills/doctrine-relations/reference.md)
- **doctrine-transactions** — Handle Doctrine transactions (ORM 3 wrapInTransaction), optimistic/pessimistic locking, flush strategies, and transaction boundaries → `content/skills/doctrine-transactions/SKILL.md` · [reference](content/skills/doctrine-transactions/reference.md)

### Tests & TDD

- **api-platform-tests** — Test API Platform resources with ApiTestCase; assert collections, items, filters, JSON schema, and authentication → `content/skills/api-platform-tests/SKILL.md` · [reference](content/skills/api-platform-tests/reference.md)
- **doctrine-fixtures-foundry** — Create test data with Zenstruck Foundry v2 factories (PersistentObjectFactory, real objects); define states, sequences, and relationships → `content/skills/doctrine-fixtures-foundry/SKILL.md` · [reference](content/skills/doctrine-fixtures-foundry/reference.md)
- **e2e-panther-playwright** — Write end-to-end tests with Symfony Panther 2.4 for browser automation or Playwright for complex scenarios → `content/skills/e2e-panther-playwright/SKILL.md` · [reference](content/skills/e2e-panther-playwright/reference.md)
- **functional-tests** — Write functional tests for Symfony controllers and HTTP endpoints using WebTestCase, getContainer, loginUser, and DAMA rollback → `content/skills/functional-tests/SKILL.md` · [reference](content/skills/functional-tests/reference.md)
- **tdd-with-pest** — Apply RED-GREEN-REFACTOR with Pest v4 (PHP 8.3+) for Symfony via the PHPUnit bridge; Foundry factories, WebTestCase, verify failures first → `content/skills/tdd-with-pest/SKILL.md` · [reference](content/skills/tdd-with-pest/reference.md)
- **tdd-with-phpunit** — Apply RED-GREEN-REFACTOR with PHPUnit 10/11 for Symfony; KernelTestCase/WebTestCase, attributes (#[Test]/#[DataProvider]), Foundry → `content/skills/tdd-with-phpunit/SKILL.md` · [reference](content/skills/tdd-with-phpunit/reference.md)
- **test-doubles-mocking** — Create test doubles with PHPUnit mocks for isolated unit testing in Symfony → `content/skills/test-doubles-mocking/SKILL.md` · [reference](content/skills/test-doubles-mocking/reference.md)

### Messenger & async

- **cqrs-and-handlers** — Implement CQRS in Symfony with separate Command and Query buses/handlers using the Messenger component → `content/skills/cqrs-and-handlers/SKILL.md` · [reference](content/skills/cqrs-and-handlers/reference.md)
- **messenger-retry-failures** — Handle message failures with retry strategies, failure transport, and recovery in Symfony Messenger (Recoverable/Unrecoverable exceptions) → `content/skills/messenger-retry-failures/SKILL.md` · [reference](content/skills/messenger-retry-failures/reference.md)
- **symfony-messenger** — Async message handling with Symfony Messenger; configure transports (RabbitMQ, Redis, Doctrine); implement handlers, middleware, and retry strategies → `content/skills/symfony-messenger/SKILL.md` · [reference](content/skills/symfony-messenger/reference.md)
- **symfony-scheduler** — Schedule recurring tasks with the Symfony Scheduler component (native since 7.x); define schedules, triggers, and integrate with Messenger → `content/skills/symfony-scheduler/SKILL.md` · [reference](content/skills/symfony-scheduler/reference.md)

### Security

- **api-platform-security** — Secure API Platform resources with security expressions, voters, securityPostValidation, and operation-level access control → `content/skills/api-platform-security/SKILL.md` · [reference](content/skills/api-platform-security/reference.md)
- **form-types-validation** — Build Symfony forms with custom Form Types, validation constraints, HTTP 422 handling, and multi-step flows → `content/skills/form-types-validation/SKILL.md` · [reference](content/skills/form-types-validation/reference.md)
- **rate-limiting** — Implement rate limiting with the Symfony RateLimiter (sliding window, token bucket, fixed window) and the #[RateLimit] controller attribute → `content/skills/rate-limiting/SKILL.md` · [reference](content/skills/rate-limiting/reference.md)
- **symfony-voters** — Implement granular authorization with Symfony Voters; decouple permission logic from controllers; test authorization separately → `content/skills/symfony-voters/SKILL.md` · [reference](content/skills/symfony-voters/reference.md)

### Architecture & services

- **config-env-parameters** — Manage Symfony configuration with .env files, parameters, secrets vault, and environment-specific settings → `content/skills/config-env-parameters/SKILL.md` · [reference](content/skills/config-env-parameters/reference.md)
- **controller-cleanup** — Refactor fat controllers into lean ones by extracting business logic to services, handlers, and invokable commands → `content/skills/controller-cleanup/SKILL.md` · [reference](content/skills/controller-cleanup/reference.md)
- **cqrs-and-handlers** — Implement CQRS in Symfony with separate Command and Query buses/handlers using the Messenger component → `content/skills/cqrs-and-handlers/SKILL.md` · [reference](content/skills/cqrs-and-handlers/reference.md)
- **interfaces-and-autowiring** — Master Symfony Dependency Injection with autowiring, #[Target] interface binding, decoration, and tagged services → `content/skills/interfaces-and-autowiring/SKILL.md` · [reference](content/skills/interfaces-and-autowiring/reference.md)
- **ports-and-adapters** — Implement Hexagonal Architecture (Ports and Adapters) in Symfony; separate domain logic from infrastructure with clear boundaries → `content/skills/ports-and-adapters/SKILL.md` · [reference](content/skills/ports-and-adapters/reference.md)
- **strategy-pattern** — Implement the Strategy pattern with Symfony's tagged services for runtime algorithm selection and extensibility → `content/skills/strategy-pattern/SKILL.md` · [reference](content/skills/strategy-pattern/reference.md)
- **symfony-cache** — Implement caching with the Symfony Cache component; configure pools, use tags for invalidation, prevent stampede → `content/skills/symfony-cache/SKILL.md` · [reference](content/skills/symfony-cache/reference.md)
- **twig-components** — Build reusable UI components with Symfony UX Twig Components (props, slots, anonymous components, CVA) for clean templates → `content/skills/twig-components/SKILL.md` · [reference](content/skills/twig-components/reference.md)
- **value-objects-and-dtos** — Design Value Objects for domain concepts and DTOs for data transfer with proper immutability (readonly) and validation → `content/skills/value-objects-and-dtos/SKILL.md` · [reference](content/skills/value-objects-and-dtos/reference.md)

### Workflow & onboarding

- **bootstrap-check** — Verify Symfony project configuration including .env, services.yaml, doctrine settings, and framework requirements → `content/skills/bootstrap-check/SKILL.md` · [reference](content/skills/bootstrap-check/reference.md)
- **brainstorming** — Structured brainstorming for Symfony projects - explore requirements, identify components, and plan architecture collaboratively → `content/skills/brainstorming/SKILL.md`
- **daily-workflow** — Daily development workflow for Symfony projects including common tasks, debugging, and productivity tips → `content/skills/daily-workflow/SKILL.md` · [reference](content/skills/daily-workflow/reference.md)
- **effective-context** — Provide effective context to the coding agent for Symfony development with relevant files, patterns, and constraints → `content/skills/effective-context/SKILL.md` · [reference](content/skills/effective-context/reference.md)
- **executing-plans** — Methodically execute implementation plans with a TDD approach, incremental commits, and continuous validation → `content/skills/executing-plans/SKILL.md` · [reference](content/skills/executing-plans/reference.md)
- **quality-checks** — Run code quality tools: PHP-CS-Fixer for style, PHPStan for static analysis, and type safety checks → `content/skills/quality-checks/SKILL.md` · [reference](content/skills/quality-checks/reference.md)
- **runner-selection** — Select and configure the appropriate command runner based on Docker Compose standard, Symfony Docker (FrankenPHP), or host environment → `content/skills/runner-selection/SKILL.md`
- **using-symfony-superpowers** — Entry point for Symfony Superpowers - lightweight workflow guidance and command map → `content/skills/using-symfony-superpowers/SKILL.md`
- **writing-plans** — Create structured implementation plans for Symfony features with clear steps, dependencies, and acceptance criteria → `content/skills/writing-plans/SKILL.md` · [reference](content/skills/writing-plans/reference.md)

## Agents (7)

Role prompts for delegated or focused work. Each one lives in
`content/agents/<name>.md`; open it and adopt it as your operating brief.

- **api-platform-builder** (implement) — Creates and configures API Platform resources with operations, DTOs, state providers, processors, and security. Handles full resource scaffolding from entity to tested API endpoint. Use for building APIs, creating resources, or configuring API Platform.
- **doctrine-architect** (analyze) — Designs Doctrine entity schemas, relationships, and migration strategies. Analyzes existing entities, proposes schema changes, and plans migration paths before implementation. Use for entity design, relationship modeling, or migration planning.
- **doctrine-performance-optimizer** (review) — Read-only performance audit of Doctrine usage: N+1 queries, fetch modes, batch processing, missing indexes, and caching opportunities. Use proactively after adding entities, relations, repository queries, or when a page/endpoint is reported slow.
- **symfony-engineer** (implement) — Implements Symfony application code following framework best practices, drawing on the superpowers-symfony skill library. Use for general Symfony coding — controllers, services, dependency injection, value objects/DTOs, forms, Twig components, configuration — when no more specialized agent (api-platform-builder, doctrine-architect, symfony-tdd-coach) fits better.
- **symfony-reviewer** (review) — Reviews Symfony code for quality, architecture, and best practices. Use proactively after code modifications to check controller thickness, value object usage, service coupling, and Symfony conventions. Triggers on code review, quality audit, or architecture check requests.
- **symfony-security-auditor** (review) — Read-only security audit of Symfony authentication and authorization: firewalls, access_control, voters, API Platform security, rate limiting, CSRF, password hashing, and input validation. Use proactively after changes to security.yaml, voters, controllers, forms, or API resources.
- **symfony-tdd-coach** (implement) — Guides TDD workflow for Symfony projects using Pest PHP or PHPUnit. Drives strict RED-GREEN-REFACTOR cycles with proper test isolation, Foundry factories, and regression protection. Use when writing tests, adding test coverage, or practicing TDD.

## Commands (13)

Named entry points; each is an alias for one skill.

- **brainstorm** — Start a structured brainstorming session for Symfony project features and architecture → skill `brainstorming`
- **execute-plan** — Execute an implementation plan methodically with TDD and continuous validation → skill `executing-plans`
- **symfony-api-resources** — Configure API Platform resources with operations and pagination → skill `api-platform-resources`
- **symfony-cache** — Implement caching strategies using Symfony Cache component → skill `symfony-cache`
- **symfony-check** — Run all quality checks (PHP-CS-Fixer, PHPStan, tests) on the Symfony project → skill `quality-checks`
- **symfony-doctrine-relations** — Guide for implementing Doctrine entity relationships (OneToMany, ManyToMany) → skill `doctrine-relations`
- **symfony-fixtures** — Create test fixtures using Foundry factories for realistic test data → skill `doctrine-fixtures-foundry`
- **symfony-messenger** — Implement async message handling with Symfony Messenger → skill `symfony-messenger`
- **symfony-migrations** — Create and manage Doctrine migrations for database schema changes → skill `doctrine-migrations`
- **symfony-tdd-pest** — Start a TDD workflow using Pest PHP for Symfony with RED-GREEN-REFACTOR cycle → skill `tdd-with-pest`
- **symfony-tdd-phpunit** — Start a TDD workflow using PHPUnit for Symfony with RED-GREEN-REFACTOR cycle → skill `tdd-with-phpunit`
- **symfony-voters** — Implement authorization logic using Symfony Voters → skill `symfony-voters`
- **write-plan** — Create a structured implementation plan for a Symfony feature → skill `writing-plans`