ai-template/.opencode/skills/php-deptrac/SKILL.md

name, description, compatibility

name	description	compatibility
php-deptrac	Guidelines for analyzing, defining, and enforcing PHP architectural rules using Deptrac.	opencode

PHP Architecture Enforcement with Deptrac

This skill provides a workflow for maintaining clean architecture in PHP projects using Deptrac.

Workflow

1. Setup & Installation

• Check if deptrac/deptrac is present in composer.json.
• If not installed, suggest: composer require --dev deptrac/deptrac.
• Ensure vendor/bin/deptrac is executable.

2. Configuration & Layer Definition

• Initialization: Use vendor/bin/deptrac init to generate a template if no config exists.
• Config File: Work with deptrac.yaml (or deptrac.php).
• Defining Layers:
  • Identify logical layers (e.g., Domain, Application, Infrastructure, UI).
  • Use collectors to map namespaces or directories to these layers.
• Defining Rules:
  • Establish allowed dependencies (e.g., Application can depend on Domain, but Domain cannot depend on Application).
  • Forbid direct dependency between siblings if required.

3. Analysis & Violation Handling

• Run Analysis: Execute vendor/bin/deptrac analyse.
• Interpret Results:
  • Analyze the violation report to identify which class is breaking which rule.
  • Check the source code to determine if it's a legitimate architectural leak or a misconfiguration.
• Correction:
  • Refactor the code to remove the illegal dependency (Preferred).
  • Adjust the rules in deptrac.yaml if the architecture has evolved.
  • Use baselines (deptrac.baseline.yaml) for legacy code that cannot be fixed immediately.

4. Integration & Verification

• Ensure Deptrac is part of the CI pipeline or local linting process.
• Run vendor/bin/deptrac as a final check before completing architectural refactoring tasks.