playbooks

home / skills / makfly / superpowers-symfony / cqrs-and-handlers

cqrs-and-handlers skill

/skills/cqrs-and-handlers

This skill helps you architect Symfony CQRS and handlers with safe checkpoints, incremental changes, and auditable decision logs.

npx playbooks add skill makfly/superpowers-symfony --skill cqrs-and-handlers

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.1 KB
---

name: symfony:cqrs-and-handlers
allowed-tools:
  - Read
  - Glob
  - Grep
description: Apply production-grade Symfony architecture and execution workflows with controlled scope and clear checkpoints. Use for cqrs and handlers tasks.
---

# Cqrs And Handlers (Symfony)

## Use when
- Refining architecture/workflows/context handling in Symfony projects.
- Planning and executing medium/complex changes safely.

## Default workflow
1. Establish current boundaries, constraints, and coupling points.
2. Propose smallest coherent architectural adjustment.
2. Execute in checkpoints with validation at each stage.
2. Summarize tradeoffs and follow-up backlog.

## Guardrails
- Use existing project patterns by default.
- Avoid broad refactors without explicit need.
- Keep decision log clear and auditable.

## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.

## Output contract
- Architecture/workflow changes.
- Checkpoint validation outcomes.
- Residual risks and next steps.

## References
- `reference.md`
- `docs/complexity-tiers.md`

Overview

This skill applies production-grade Symfony architecture and controlled execution workflows focused on CQRS and handler design. It helps refine boundaries, introduce minimal safe changes, and run work in validated checkpoints to reduce risk. The goal is clear, auditable decisions and a lightweight follow-up backlog for further improvements.

How this skill works

I inspect current boundaries, coupling points, and existing project patterns to avoid unnecessary wide refactors. I propose the smallest coherent architectural adjustment, then execute the change in discrete checkpoints with validation at each stage. Each checkpoint produces a validation outcome, a short decision record, and noted residual risks with recommended next steps.

When to use it

  • Refining architecture and context handling in Symfony projects using CQRS
  • Planning and executing medium or complex changes that must be low-risk
  • Introducing or reorganizing command/query handlers without disrupting runtime behavior
  • When you need auditable decisions and clear rollback/validation points
  • Preparing a change that will be delivered incrementally across teams

Best practices

  • Default to existing project patterns; only deviate when benefits clearly outweigh cost
  • Keep changes minimal and coherent to maintain deployability at each checkpoint
  • Record a concise decision log for each architectural step and validation result
  • Validate behavior at every checkpoint with unit and integration checks
  • Avoid broad, simultaneous refactors; break work into verifiable increments

Example use cases

  • Introduce a new query handler and migrate a single consumer to the new interface in one checkpoint
  • Split a large command handler into smaller units and validate side effects in staged deployments
  • Add explicit context propagation (e.g., tenant or user) into handler pipelines with backward-compatible checks
  • Rework handler registration (autowiring/config) for better testability and validate with integration tests
  • Plan and execute a safe migration from synchronous handlers to queued message handling incrementally

FAQ

How large should a checkpoint be?

Make checkpoints small enough to validate behavior and roll back if needed; a single handler change or one caller migration is a good target.

What testing is required at each checkpoint?

Unit tests for the changed units, integration tests for end-to-end flows touched, and smoke checks on staging are minimum requirements.