superpowers-symfony

Superpowers Symfony — a Symfony skill library for coding agents

Version-accurate Symfony expertise for AI coding agents. 44 expert skills, 7 specialized agents and 13 commands covering API Platform v4, Doctrine ORM 3, TDD with Pest & PHPUnit, Symfony Messenger, security/voters, and DDD / hexagonal architecture — usable from Claude Code, Codex CLI, Grok Build, OpenCode, Cursor, Windsurf, GitHub Copilot, Gemini CLI, aider, or by hand.

Superpowers Symfony gives coding agents deep, version-accurate Symfony expertise — from Doctrine schema design and API Platform REST/GraphQL APIs to test-driven development, async Messenger workflows, caching, rate limiting, and clean architecture. It targets Symfony 7.4 LTS and 8.x (6.4 LTS as legacy), API Platform v4 (v3 legacy), and Doctrine ORM 3 — so the guidance, signatures and code examples match the framework you actually run.

The content is deliberately vendor-neutral: skills are plain Markdown in the open Agent Skills layout, and the per-harness packaging is generated from them.

How it is organised

   content/        ← the source of truth: 44 skills, 7 agents, 13 commands
       │
       ├── read directly by ─────► Claude Code   (component paths in plugin.json)
       │                           OpenCode      (.opencode/skills → content/skills)
       │                           Grok Build    (.agents/skills   → content/skills)
       │
       └── bun run build ────────► AGENTS.md · skills-map.md · dist/**
                                   Codex · Cursor · Windsurf · Copilot · Gemini · aider

Nothing under dist/ is written by hand, and CI fails if it drifts from content/.

Installation

Harness	Mechanism	How
Claude Code	plugin marketplace	/plugin marketplace add dev-toolings/superpowers-symfony then /plugin install superpowers-symfony@superpowers-symfony
Codex CLI	AGENTS.md + prompts	copy AGENTS.md into your project, cp dist/codex/prompts/*.md ~/.codex/prompts/
Grok Build	AGENTS.md + .agents/	copy AGENTS.md, then ln -s "$PWD/content/skills" .agents/skills and cp -R dist/agents/commands .agents/commands — then trust the folder (see below)
OpenCode	native skills + agents	ln -s "$PWD/content/skills" .opencode/skills, cp -R dist/opencode/agent .opencode/agent
Cursor	rules	cp dist/cursor/rules/*.mdc .cursor/rules/
Windsurf	rules	cp dist/windsurf/rules/*.md .windsurf/rules/
GitHub Copilot	instructions + custom agents	cp dist/copilot/copilot-instructions.md .github/, cp dist/copilot/instructions/*.md .github/instructions/, cp dist/copilot/agents/*.agent.md .github/agents/
Gemini CLI	GEMINI.md + commands	cp dist/gemini/GEMINI.md ., cp -R dist/gemini/commands/symfony ~/.gemini/commands/
aider	conventions	cp dist/aider/CONVENTIONS.md AGENTS.md ., cp dist/aider/.aider.conf.yml .
Anything else	manual	copy AGENTS.md; it routes to the right content/skills/<name>/SKILL.md

Full per-harness instructions: dist/README.md.

Grok Build trusts nothing by default. Until you accept the trust prompt for a directory, it loads neither project instructions nor project skills — grok inspect reports Project trusted: no and simply lists none of them. Run grok once in the project, accept, then confirm with grok inspect.

Verified

Harness	Check	Result
Claude Code	claude plugin details	44 skills · 7 agents · 13 commands · SessionStart hook
Grok Build	grok inspect + one-shot prompt	44/44 skills via .agents/skills, AGENTS.md loaded, routed correctly
OpenCode	opencode debug skill / agent list	44/44 skills, 7/7 agents as subagents
Codex CLI	codex exec one-shot prompt	AGENTS.md loaded, routed correctly

Grok Code Fast and similar hosted models inherit whatever format their host harness uses — nothing specific to install for them.

Claude Code, project-scoped

{
  "extraKnownMarketplaces": {
    "superpowers-symfony": {
      "source": { "source": "github", "repo": "dev-toolings/superpowers-symfony" }
    }
  },
  "enabledPlugins": { "superpowers-symfony@superpowers-symfony": true }
}

Runtime detection

bin/symfony-context detects the Symfony version, API Platform, the Docker setup (Symfony Docker / DDEV / Compose / host) and the test framework, then prints the correctly prefixed bin/console, composer and test commands.

./bin/symfony-context                    # JSON
./bin/symfony-context --format=markdown  # a context block for any agent
./bin/symfony-context --format=env       # for scripts and CI

Claude Code runs it automatically at session start. Other harnesses are told to run it first by AGENTS.md and by the generated rule indexes.

Skills

API Platform

Skill	Description
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
api-platform-filters	Implement API Platform filters - v4 Parameters API (QueryParameter) and legacy #[ApiFilter] - for search, date, range, boolean, and custom filtering
api-platform-resources	Configure API Platform v4 resources with explicit operations, pagination, and typed OpenAPI for clean, versioned REST/GraphQL APIs
api-platform-security	Secure API Platform resources with security expressions, voters, securityPostValidation, and operation-level access control
api-platform-serialization	Control API Platform serialization with groups, #[Context], IRI links (readableLink/writableLink), and custom context builders
api-platform-state-providers	Master API Platform v4 State Providers and Processors (ProviderInterface/ProcessorInterface) to decouple data retrieval and persistence from entities
api-platform-tests	Test API Platform resources with ApiTestCase; assert collections, items, filters, JSON schema, and authentication
api-platform-versioning	Evolve API Platform APIs via deprecation (deprecationReason/sunset, RFC 8594/9745), the recommended alternative to versioning; plus path/header strategies

Doctrine ORM

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

Tests & TDD

Skill	Description
api-platform-tests	Test API Platform resources with ApiTestCase; assert collections, items, filters, JSON schema, and authentication
doctrine-fixtures-foundry	Create test data with Zenstruck Foundry v2 factories (PersistentObjectFactory, real objects); define states, sequences, and relationships
e2e-panther-playwright	Write end-to-end tests with Symfony Panther 2.4 for browser automation or Playwright for complex scenarios
functional-tests	Write functional tests for Symfony controllers and HTTP endpoints using WebTestCase, getContainer, loginUser, and DAMA rollback
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
tdd-with-phpunit	Apply RED-GREEN-REFACTOR with PHPUnit 10/11 for Symfony; KernelTestCase/WebTestCase, attributes (#[Test]/#[DataProvider]), Foundry
test-doubles-mocking	Create test doubles with PHPUnit mocks for isolated unit testing in Symfony

Messenger & async

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

Security

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

Architecture & services

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

Workflow & onboarding

Skill	Description