playbooks

home / skills / makfly / superpowers-symfony / ports-and-adapters

ports-and-adapters skill

/skills/ports-and-adapters

This skill guides Symfony architecture and workflow changes with controlled checkpoints and validation, ensuring safe, auditable ports and adapters adaptations.

npx playbooks add skill makfly/superpowers-symfony --skill ports-and-adapters

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:ports-and-adapters
allowed-tools:
  - Read
  - Glob
  - Grep
description: Apply production-grade Symfony architecture and execution workflows with controlled scope and clear checkpoints. Use for ports and adapters tasks.
---

# Ports And Adapters (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 a production-grade Ports and Adapters (Hexagonal) approach to Symfony applications with controlled scope and clear checkpoints. It provides a reproducible workflow to propose, execute, and validate architectural changes while preserving existing patterns and minimizing risk. The output includes proposed adjustments, checkpoint validation results, and a follow-up backlog of residual tasks.

How this skill works

I inspect current boundaries, coupling points, and context handling in the Symfony codebase to identify the smallest coherent architectural adjustment that delivers value. Changes are executed in incremental checkpoints with explicit validation criteria and roll-forward/rollback guidance. Each checkpoint produces a decision record, test outcomes, and a short summary of tradeoffs and residual risks.

When to use it

  • Refining architecture or execution workflows in an existing Symfony project.
  • Planning medium to complex changes that must be executed safely and audibly.
  • Introducing ports-and-adapters patterns to isolate domain logic from framework concerns.
  • When you need a clear sequence of checkpoints and validation for safe deployments.
  • Onboarding teams to a consistent, auditable approach to architecture changes.

Best practices

  • Default to existing project patterns and only deviate when justified.
  • Propose the smallest coherent change that achieves the objective.
  • Break work into checkpoints with concrete validation criteria and automated tests.
  • Keep a clear, auditable decision log for every architectural change.
  • Avoid broad refactors without explicit business or technical necessity.

Example use cases

  • Introduce an Input/Output port layer for a legacy service to enable independent testing.
  • Migrate a repository implementation behind an adapter to remove framework coupling.
  • Add a new application service with a clear adapter boundary and automated checkpoint tests.
  • Validate and deploy an incremental change that separates HTTP controllers from domain logic.
  • Create a backlog of follow-up tasks after a guarded architectural adjustment.

FAQ

How large should each checkpoint be?

Each checkpoint should be the smallest unit that can be validated independently—ideally a single adapter, interface, or service change with automated tests.

What happens if a checkpoint fails validation?

The workflow includes roll-back guidance and a remedial plan: fix tests, adjust the scope, or revert to the previous stable state before proceeding.